Fonctions HTTP
Les fonctions HTTP vous permettent d'appeler votre fonction via une requête HTTP(S). Pour autoriser la sémantique HTTP, les signatures de fonction HTTP acceptent des arguments HTTP spécifiques.
Vous pouvez configurer les fonctions HTTP pour contrôler si elles peuvent être déclenchées à la fois par les protocoles HTTPS et HTTP, ou par le protocole HTTPS uniquement. Pour en savoir plus, consultez la section Niveaux de sécurité.
Exécuter les exemples
Pour exécuter les exemples de ce document, assurez-vous d'avoir configuré votre environnement d'exécution comme décrit dans ce guide de démarrage rapide. Veillez en particulier à cloner l'exemple de dépôt sur votre ordinateur local pour vous assurer que tous les fichiers requis sont présents dans votre environnement.
Exemple d'utilisation
L'exemple ci-dessous montre comment traiter une requête HTTP POST contenant un paramètre name
:
Node.js
Python
Go
Java
C#
Ruby
PHP
La commande suivante montre comment appeler la fonction et lui transmettre un paramètre à l'aide de curl
:
curl -X POST HTTP_TRIGGER_ENDPOINT -H "Content-Type:application/json" -d '{"name":"Jane"}'
où HTTP_TRIGGER_ENDPOINT
est l'URL de la fonction, obtenue lorsque la fonction est déployée. Pour en savoir plus, consultez la page Déclencheurs HTTP.
Faites l'essai
Si vous débutez sur Google Cloud, créez un compte pour évaluer les performances de Cloud Functions en conditions réelles. Les nouveaux clients bénéficient également de 300 $ de crédits gratuits pour exécuter, tester et déployer des charges de travail.
Profiter d'un essai gratuit de Cloud FunctionsNiveaux de sécurité
La fonctionnalité de niveau de sécurité contrôle si l'URL d'une fonction HTTP n'accepte que le protocole HTTPS, ou les protocoles HTTP et HTTPS. Le fonctionnement par défaut consiste à n'accepter que le protocole HTTPS.
Lorsqu'une fonction HTTP est configurée pour être déclenchée uniquement via le protocole HTTPS, les utilisateurs qui tentent d'utiliser le protocole HTTP sont redirigés.
Vous spécifiez le niveau de sécurité d'une fonction HTTP lors du déploiement :
Si vous déployez votre fonction à l'aide de Google Cloud CLI, vous pouvez définir son niveau de sécurité à l'aide de l'option
--security-level
. Ses valeurs possibles sontsecure-optional
ousecure-always
, qui est la valeur par défaut. Exemple :gcloud functions deploy
FUNCTION_NAME
--trigger-http --security-level=secure-optional...Si vous déployez votre fonction depuis Cloud Console, cochez la case Exiger le protocole HTTPS pour indiquer si la fonction doit exiger le protocole HTTPS.
Si la fonction peut être déclenchée avec HTTP ou HTTPS, le code de la fonction peut examiner la valeur de l'en-tête de requête X-Forwarded-Proto pour déterminer le protocole utilisé. La valeur de cet en-tête est https pour une requête sécurisée et http pour toutes les autres requêtes.
Frameworks HTTP
Pour gérer HTTP, Cloud Functions utilise un framework HTTP spécifique à chaque environnement d'exécution :
Exécution | Framework HTTP |
---|---|
Node.js | Express 4.17.1 |
Python | Flask 1.0.2 |
Go | Interface http.HandlerFunc standard |
Java | Framework des fonctions de l'API Java |
.NET | Framework des fonctions pour .NET |
Ruby | Functions Framework for Ruby |
PHP | Framework des fonctions pour PHP |
Arrêter des fonctions HTTP
Si une fonction crée des tâches en arrière-plan (telles que des threads, des objets future, des objets Promise
Node.js, des rappels ou des processus système), vous devez arrêter ces tâches ou les résoudre avant de renvoyer une réponse HTTP. Toutes les tâches non terminées avant une réponse HTTP peuvent rester en suspens et entraîner un comportement indéfini.
Analyser des requêtes HTTP
L'exemple ci-dessous décrit comment lire les requêtes HTTP dans différents formats :Node.js
Dans Node.js, le corps de la requête est automatiquement analysé en fonction de l'en-tête content-type
et mis à disposition via les arguments de votre fonction HTTP.
Python
Go
Java
C#
Ruby
PHP
Gérer les requêtes CORS
Le partage de ressources entre origines multiples (CORS, Cross-Origin Resource Sharing) permet aux applications exécutées sur un domaine d'accéder au contenu d'un autre domaine, par exemple en autorisant yourdomain.com
à envoyer des requêtes à region-project.cloudfunctions.net/yourfunction
.
Si CORS n'est pas configuré correctement, vous risquez d'obtenir des erreurs de ce type :
XMLHttpRequest cannot load https://region-project.cloudfunctions.net/function. No 'Access-Control-Allow-Origin' header is present on the requested resource. Origin 'http://yourdomain.com' is therefore not allowed access.
Requête préliminaire
CORS se compose de deux requêtes :
- Une requête
OPTIONS
préliminaire - Une requête principale qui suit la requête
OPTIONS
La requête préliminaire contient des en-têtes indiquant quelle méthode (Access-Control-Request-Method
) et quels en-têtes supplémentaires (Access-Control-Request-Headers
) seront envoyés dans la requête principale, ainsi que l'origine de la requête principale (Origin
).
Pour traiter une requête préliminaire, vous devez définir les en-têtes Access-Control-Allow-*
appropriés afin d'assurer la correspondance avec les requêtes que vous souhaitez accepter :
Node.js
Python
Go
Java
C#
Ruby
PHP
Vous pouvez également utiliser une bibliothèque tierce pour gérer vos requêtes CORS.
Limites
Les requêtes CORS préliminaires sont envoyées sans en-tête Authorization
. Elles seront donc refusées pour toutes les fonctions HTTP non publiques. Comme les requêtes préliminaires échouent, la requête principale échouera également.
Les fonctions HTTP requièrent l'authentification par défaut. Ainsi, voici les options qui vous permettront de contourner cette limitation :
- Rendez votre fonction publique.
- Pour rendre votre fonction publique, vous pouvez soit la déployer avec l'option
--allow-unauthenticated
, soit utiliser la console pour attribuer le rôle de demandeur Cloud Functions à tous les utilisateurs (allUsers
). Vous devez ensuite gérer le CORS et l'authentification dans le code de la fonction.
- Pour rendre votre fonction publique, vous pouvez soit la déployer avec l'option
- Hébergez votre application Web et votre fonction sur le même domaine afin d'éviter les requêtes CORS préliminaires.
- Déployez un proxy Cloud Endpoints et activez CORS.
Héberger sur le même domaine
Au lieu de mettre en œuvre CORS, vous avez tout intérêt à héberger votre site Web et vos fonctions sur le même domaine. Comme les requêtes auront alors la même origine, CORS ne sera pas appliqué. Cela simplifiera considérablement votre code.
La façon la plus simple de procéder consiste à intégrer l’hébergement Firebase à Google Cloud Functions.
Gérer CORS à l'aide de Cloud Endpoints
Vous pouvez déployer un proxy Cloud Endpoints et activer CORS.
Si vous souhaitez ajouter des fonctionnalités d'authentification, vous pouvez également activer la validation des jetons d'identification Google.
Gérer les méthodes HTTP
Les fonctions HTTP acceptent toutes les méthodes HTTP. L'exemple suivant montre comment effectuer différentes actions en fonction de la méthode HTTP obtenue (par exemple, GET
et PUT
) :
Node.js
Python
Go
Java
C#
Ruby
PHP
Gérer les types de contenus
Pour Node.js, Cloud Functions analyse les types de contenus du corps de la requête de application/json
et de application/x-www-form-urlencoded
, comme illustré ci-dessus. Les types de contenus en texte brut (text/plain
) sont transmis sous forme de chaînes en utilisant UTF-8 comme encodage par défaut (ou un encodage personnalisé fourni dans l'en-tête content-type
).
D'autres types de contenus sont accessibles en inspectant l'argument de votre fonction HTTP. Les méthodes pour ce faire varient selon le langage.
L'exemple ci-dessous gère une requête avec un type de contenu text/xml
:
Node.js
La propriétérawBody
contient les octets non analysés du corps de la requête.
Python
Go
Java
Données multipart
L'exemple suivant montre comment traiter des données avec un type de contenu multipart/form-data
. Selon le langage choisi, vous devrez peut-être utiliser une bibliothèque d'analyse.
Node.js
Python
Go
Java
C#
Ruby
PHP
Importer des fichiers depuis Cloud Storage
Le traitement des fichiers est un cas d'utilisation courant pour Cloud Functions. Pour les fichiers volumineux ou nécessitant un stockage permanent au-delà d'une seule requête, vous pouvez utiliser Cloud Storage comme point d'entrée pour vos fichiers importés. Pour ce faire, vous devez générer une URL signée, qui fournit un accès en écriture temporaire à un bucket Cloud Storage.
Si vous utilisez Cloud Functions directement, générez une URL signée à partir de la bibliothèque cliente Cloud Storage appropriée.L'importation de fichiers dans une fonction Cloud Functions à l'aide de Cloud Storage est un processus en trois étapes :
Les clients appellent directement une fonction Cloud Functions pour récupérer une URL signée.
Les clients envoient ensuite les données du fichier à l'URL signée via une requête HTTP PUT.
Une deuxième fonction Cloud Functions est déclenchée par une mutation dans le bucket de stockage en vue du traitement ultérieur du fichier.
Consultez ci-dessous l'exemple d'utilisation de la bibliothèque cliente Cloud Storage pour générer une URL signée.
Les fonctions Cloud ont un "identifiant d'application par défaut" qui n'inclut généralement pas l'autorisation iam.serviceAccounts.signBlob
. Pour y accéder, vous devez d'abord vous assurer que le compte de service de votre fonction détient le rôle approprié. Pour cela, utilisez Cloud Console ou l'outil de ligne de commande gcloud
:
Console
Pour vous assurer que le compte de service de votre fonction détient le rôle approprié, il est possible de modifier directement les rôles IAM d'un compte :
- Accédez à Google Cloud Console :
- Sélectionnez le compte approprié et choisissez Éditeur > Comptes de service > Générateur de jetons de compte de service.
gcloud
Pour vous assurer que le compte de service de votre fonction détient le rôle approprié, exécutez la commande suivante. Le rôle serviceAccountTokenCreator
prédéfini dispose de l'autorisation iam.serviceAccounts.signBlob
dont vous avez besoin :
gcloud projects add-iam-policy-binding YOUR_PROJECT \ --member serviceAccount:YOUR_SERVICE_ACCOUNT --role roles/iam.serviceAccountTokenCreator
Vous pouvez déterminer le compte de service utilisé par vos fonctions à l'aide de Cloud Console ou de l'outil de ligne de commande gcloud
:
Console
Pour déterminer le compte de service utilisé par vos fonctions à l'aide de Cloud Console, procédez comme suit :
Accédez à Google Cloud Console :
Sélectionnez la fonction que vous souhaitez inspecter dans la liste.
Le compte de service est visible sur la page des détails de la fonction.
gcloud
Pour déterminer le compte de service utilisé par vos fonctions, exécutez la commande suivante et recherchez la propriété serviceAccountEmail
:
gcloud beta functions describe YOUR_FUNCTION_NAME
Voici un exemple de génération d'URL signée :
Node.js
Python
Go
Java
C#
Lorsque le client importe un fichier dans l'URL signée, vous pouvez déclencher une deuxième fonction à partir de cette mutation si vous souhaitez effectuer une autre action sur l'importation. Consultez le tutoriel sur Cloud Storage pour en savoir plus sur le déclenchement d'une fonction Cloud après des modifications apportées à un bucket Cloud Storage.
Étapes suivantes
- Déployer des fonctions Cloud Functions
- Appeler des fonctions HTTP
- Tutoriel sur les fonctions HTTP Cloud Functions