Principes de base de l’invocation d’une URL de fonction Charges utiles de demandes et de réponses

Invocation d’URL de fonctions Lambda

Une URL de fonction est un point de terminaison HTTP(S) dédié pour votre fonction Lambda. Vous pouvez créer et configurer une URL de fonction via la console Lambda ou l’API Lambda.

Astuce

Lambda propose deux méthodes pour invoquer votre fonction via un point de terminaison HTTP : les URL de fonction et Amazon API Gateway. Si vous ne savez pas quelle est la meilleure méthode pour votre cas d’utilisation, consultez Sélection d’une méthode pour invoquer votre fonction Lambda à l’aide d’une requête HTTP.

Lorsque vous créez une URL de fonction, Lambda génère automatiquement un point de terminaison URL unique pour vous. Une fois que vous avez créé une URL de fonction, son point de terminaison URL ne change jamais. Les points de terminaison URL de fonction ont le format suivant :


https://<url-id>.lambda-url.<region>.on.aws

Note

Les URL de fonction ne sont pas prises en charge dans les Régions AWS suivantes : Asie-Pacifique (Hyderabad) (ap-south-2), Asie-Pacifique (Melbourne) (ap-southeast-4), Asie-Pacifique (Malaisie) (ap-southeast-5), Asie-Pacifique (Nouvelle-Zélande) (ap-southeast-6), Asie-Pacifique (Thaïlande) (ap-southeast-7), Asie-Pacifique (Taipei) (ap-east-2), Canada Ouest (Calgary) (ca-west-1), Europe (Espagne) (eu-south-2), Europe (Zurich) (eu-central-2), Israël (Tel Aviv) (il-central-1) et Moyen-Orient (EAU) (me-central-1).

Les URL de fonctions sont compatibles avec la pile double, prenant en charge les adresses IPv4 et IPv6. Après avoir configuré votre URL de fonction, vous pouvez invoquer votre fonction à travers son point de terminaison HTTP(S) via un navigateur Web, curl, Postman, ou n’importe quel client HTTP. Pour invoquer l’URL d’une fonction, vous devez avoir les autorisations lambda:InvokeFunctionUrl et lambda:InvokeFunction. Pour de plus amples informations, consultez Contrôle d’accès.

Rubriques

Principes de base de l’invocation d’une URL de fonction
Charges utiles de demandes et de réponses

Principes de base de l’invocation d’une URL de fonction

Si votre URL de votre fonction utilise le type d’authentification AWS_IAM, vous devez signer chaque demande HTTP en utilisant AWSSignature Version 4 (SigV4). Des outils comme Postman offrent des moyens intégrés de signer vos demandes avec SigV4.

Si vous n’utilisez pas d’outil pour signer des demandes HTTP sur l’URL de votre fonction, vous devez signer manuellement chaque demande à l’aide de SigV4. Lorsque l’URL de votre fonction reçoit une demande, Lambda calcule également la signature SigV4. Lambda traite la demande uniquement si les signatures correspondent. Pour obtenir des instructions sur la signature manuelle de vos demandes avec SigV4, consultez Signature de demandes AWS avec Signature Version 4 dans le Guide Référence générale d'Amazon Web Services.

Si l’URL de votre fonction utilise le type d’authentification NONE, vous n’avez pas besoin de signer vos demandes avec SigV4. Vous pouvez invoquer votre fonction via un navigateur Web, curl, Postman ou n’importe quel client HTTP.

Pour tester des demandes GET simples vers votre fonction, utilisez un navigateur web. Par exemple, si l’URL de votre fonction est https://abcdefg.lambda-url.us-east-1.on.aws, et si elle prend en compte un paramètre de chaîne message, l’URL de votre demande peut se présenter comme suit :


https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld

Pour tester d’autres demandes HTTP, telles qu’une demande POST, vous pouvez utiliser un outil tel que curl. Par exemple, si vous souhaitez inclure certaines données JSON dans une demande POST pour l’URL de votre fonction, vous pouvez utiliser la commande curl suivante :


curl -v 'https://abcdefg.lambda-url.us-east-1.on.aws/?message=HelloWorld' \
-H 'content-type: application/json' \
-d '{ "example": "test" }'

Charges utiles de demandes et de réponses

Lorsqu’un client appelle l’URL de votre fonction, Lambda mappe la demande sur un objet événement avant de la transmettre à votre fonction. La réponse de votre fonction est ensuite mappée à une réponse HTTP que Lambda renvoie au client via l’URL de la fonction.

Les formats d’événements de demande et de réponse suivent le même schéma que le format de charge utile version 2.0 d’Amazon API Gateway.

Format de la charge utile de demande

Une charge utile de demande a la structure suivante :


{
  "version": "2.0",
  "routeKey": "$default",
  "rawPath": "/my/path",
  "rawQueryString": "parameter1=value1&parameter1=value2&parameter2=value",
  "cookies": [
    "cookie1",
    "cookie2"
  ],
  "headers": {
    "header1": "value1",
    "header2": "value1,value2"
  },
  "queryStringParameters": {
    "parameter1": "value1,value2",
    "parameter2": "value"
  },
  "requestContext": {
    "accountId": "123456789012",
    "apiId": "<urlid>",
    "authentication": null,
    "authorizer": {
        "iam": {
                "accessKey": "AKIA...",
                "accountId": "111122223333",
                "callerId": "AIDA...",
                "cognitoIdentity": null,
                "principalOrgId": null,
                "userArn": "arn:aws:iam::111122223333:user/example-user",
                "userId": "AIDA..."
        }
    },
    "domainName": "<url-id>.lambda-url.us-west-2.on.aws",
    "domainPrefix": "<url-id>",
    "http": {
      "method": "POST",
      "path": "/my/path",
      "protocol": "HTTP/1.1",
      "sourceIp": "123.123.123.123",
      "userAgent": "agent"
    },
    "requestId": "id",
    "routeKey": "$default",
    "stage": "$default",
    "time": "12/Mar/2020:19:03:58 +0000",
    "timeEpoch": 1583348638390
  },
  "body": "Hello from client!",
  "pathParameters": null,
  "isBase64Encoded": false,
  "stageVariables": null
}

Paramètre	Description	Exemple
`version`	La version du format de la charge utile pour cet événement. Les URL de fonctions Lambda prennent actuellement en charge le format de charge utile version 2.0.	`2.0`
`routeKey`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `$default` comme espace réservé.	`$default`
`rawPath`	Chemin d’accès de la demande. Par exemple, si l’URL de la demande est `https://{url-id}.lambda-url.{region}.on.aws/example/test/demo`, alors la valeur du chemin brut est `/example/test/demo`.	`/example/test/demo`
`rawQueryString`	La chaîne brute contenant les paramètres de la chaîne de la requête de la demande. Les caractères pris en charge sont les suivants : `a-z`, `A-Z`, `0-9`, `.`, `_`, `-`, `%`, `&`, `=`, et `+`.	`"?parameter1=value1&parameter2=value2"`
`cookies`	Un tableau contenant tous les cookies envoyés dans le cadre de la demande.	`["Cookie_1=Value_1", "Cookie_2=Value_2"]`
`headers`	La liste des en-têtes de demande, présentée sous forme de paires valeur-clé.	`{"header1": "value1", "header2": "value2"}`
`queryStringParameters`	Paramètres de requête pour la demande. Par exemple, si l’URL de la demande est `https://{url-id}.lambda-url.{region}.on.aws/example?name=Jane`, alors la valeur `queryStringParameters` est un objet JSON avec une clé `name` et une valeur `Jane`.	`{"name": "Jane"}`
`requestContext`	Un objet qui contient des informations supplémentaires sur la demande, comme `requestId`, l’heure de la demande, et l’identité de l’appelant s’il est autorisé via Gestion des identités et des accès AWS (IAM).
`requestContext.accountId`	L’identifiant Compte AWS du propriétaire de la fonction.	`"123456789012"`
`requestContext.apiId`	L’identifiant de l’URL de la fonction.	`"33anwqw8fj"`
`requestContext.authentication`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `null`.	`null`
`requestContext.authorizer`	Un objet qui contient des informations sur l’identité de l’appelant si l’URL de la fonction utilise le type d’authentification `AWS_IAM`. Sinon, Lambda définit cette valeur sur `null`.
`requestContext.authorizer.iam.accessKey`	La clé d’accès de l’identité de l’appelant.	`"AKIAIOSFODNN7EXAMPLE"`
`requestContext.authorizer.iam.accountId`	L’identifiant Compte AWS de l’identité de l’appelant.	`"111122223333"`
`requestContext.authorizer.iam.callerId`	L’ID (ID d’utilisateur) de l’appelant.	`"AIDACKCEVSQ6C2EXAMPLE"`
`requestContext.authorizer.iam.cognitoIdentity`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `null` ou l’exclut de JSON.	`null`
`requestContext.authorizer.iam.principalOrgId`	L’ID de l’organisation du principal associé à l’ID de l’appelant.	`"AIDACKCEVSQORGEXAMPLE"`
`requestContext.authorizer.iam.userArn`	L’Amazon Resource Name (ARN) utilisateur de l’identité de l’appelant.	`"arn:aws:iam::111122223333:user/example-user"`
`requestContext.authorizer.iam.userId`	L’identifiant utilisateur de l’identité de l’appelant.	`"AIDACOSFODNN7EXAMPLE2"`
`requestContext.domainName`	Le nom de domaine de l’URL de la fonction.	`"<url-id>.lambda-url.us-west-2.on.aws"`
`requestContext.domainPrefix`	Le nom de domaine de l’URL de la fonction.	`"<url-id>"`
`requestContext.http`	Un objet qui contient des informations sur la demande HTTP.
`requestContext.http.method`	La méthode HTTP utilisée dans cette demande. Les valeurs valides sont les suivantes : `GET`, `POST`, `PUT`, `HEAD`, `OPTIONS`, `PATCH` et `DELETE`.	`GET`
`requestContext.http.path`	Chemin d’accès de la demande. Par exemple, si l’URL de la demande est `https://{url-id}.lambda-url.{region}.on.aws/example/test/demo`, alors la valeur du chemin est `/example/test/demo`.	`/example/test/demo`
`requestContext.http.protocol`	Le protocole de la demande.	`HTTP/1.1`
`requestContext.http.sourceIp`	L’adresse IP source de la connexion TCP immédiate qui fait la demande.	`123.123.123.123`
`requestContext.http.userAgent`	La valeur de l’en-tête de la demande Utilisateur-Agent.	`Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0`
`requestContext.requestId`	L’identifiant de la demande d’invocation. Vous pouvez utiliser cet ID pour suivre les journaux d’invocation liés à votre fonction.	`e1506fd5-9e7b-434f-bd42-4f8fa224b599`
`requestContext.routeKey`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `$default` comme espace réservé.	`$default`
`requestContext.stage`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `$default` comme espace réservé.	`$default`
`requestContext.time`	Horodatage de la demande.	`"07/Sep/2021:22:50:22 +0000"`
`requestContext.timeEpoch`	L’horodatage de la demande, en heure d’époque Unix.	`"1631055022677"`
`body`	Le corps de la demande. Si le type de contenu de la demande est binaire, le corps est codé en base64.	`{"key1": "value1", "key2": "value2"}`
`pathParameters`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `null` ou l’exclut de JSON.	`null`
`isBase64Encoded`	`TRUE` si le corps est une charge utile binaire et codé en base64. Sinon `FALSE`.	`FALSE`
`stageVariables`	Les URL de fonctions n’utilisent pas ce paramètre. Lambda le définit sur `null` ou l’exclut du JSON.	`null`

Format de la charge utile de la réponse

Lorsque votre fonction renvoie une réponse, Lambda analyse la réponse et la convertit en réponse HTTP. Les charges utiles de la réponse de fonction ont le format suivant :


{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": "{ \"message\": \"Hello, world!\" }",
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}

Lambda déduit le format de réponse pour vous. Si votre fonction renvoie un JSON valide et ne renvoie pas un statusCode, Lambda assume ce qui suit :

statusCode is 200.

Note
Les valeurs de statusCode valides sont comprises entre 100 et 599.
content-type is application/json.
body est la réponse de la fonction.
isBase64Encoded is false.

Les exemples suivants montrent comment la sortie de votre fonction Lambda est mappée à la charge utile de réponse et comment la charge utile de réponse est mappée à la réponse HTTP finale. Lorsque le client invoque l’URL de votre fonction, il voit la réponse HTTP.

Exemple de sortie pour une réponse de chaîne

Sortie de la fonction Lambda Sortie de réponse interprétée Réponse HTTP (ce que voit le client)

Sortie de la fonction Lambda	Sortie de réponse interprétée	Réponse HTTP (ce que voit le client)
`"Hello, world!"`	`{ "statusCode": 200, "body": "Hello, world!", "headers": { "content-type": "application/json" }, "isBase64Encoded": false }`	`HTTP/2 200 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 15 "Hello, world!"`


"Hello, world!"


{
  "statusCode": 200,
  "body": "Hello, world!",
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}


HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 15

"Hello, world!"

Exemple de sortie pour une réponse JSON

Sortie de la fonction Lambda Sortie de réponse interprétée Réponse HTTP (ce que voit le client)

Sortie de la fonction Lambda	Sortie de réponse interprétée	Réponse HTTP (ce que voit le client)
`{ "message": "Hello, world!" }`	`{ "statusCode": 200, "body": { "message": "Hello, world!" }, "headers": { "content-type": "application/json" }, "isBase64Encoded": false }`	`HTTP/2 200 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 34 { "message": "Hello, world!" }`


{
  "message": "Hello, world!"
}


{
  "statusCode": 200,
  "body": {
    "message": "Hello, world!"
  },
  "headers": {
    "content-type": "application/json"
  },
  "isBase64Encoded": false
}


HTTP/2 200
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 34

{
  "message": "Hello, world!"
}

Exemple de sortie pour une réponse personnalisée

Sortie de la fonction Lambda Sortie de réponse interprétée Réponse HTTP (ce que voit le client)

Sortie de la fonction Lambda	Sortie de réponse interprétée	Réponse HTTP (ce que voit le client)
`{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "isBase64Encoded": false }`	`{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "isBase64Encoded": false }`	`HTTP/2 201 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 27 my-custom-header: Custom Value { "message": "Hello, world!" }`


{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "isBase64Encoded": false
}


{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "isBase64Encoded": false
}


HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value

{
  "message": "Hello, world!"
}

Cookies

Pour renvoyer des cookies depuis votre fonction, n’ajoutez pas manuellement des en-têtes set-cookie. Incluez plutôt les cookies dans votre objet de charge utile de réponse. Lambda les interprète automatiquement et les ajoute comme en-têtes set-cookie de votre réponse HTTP, comme dans l’exemple suivant.

Sortie de la fonction Lambda Réponse HTTP (ce que voit le client)

Sortie de la fonction Lambda	Réponse HTTP (ce que voit le client)
`{ "statusCode": 201, "headers": { "Content-Type": "application/json", "My-Custom-Header": "Custom Value" }, "body": JSON.stringify({ "message": "Hello, world!" }), "cookies": [ "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT", "Cookie_2=Value2; Max-Age=78000" ], "isBase64Encoded": false }`	`HTTP/2 201 date: Wed, 08 Sep 2021 18:02:24 GMT content-type: application/json content-length: 27 my-custom-header: Custom Value set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT set-cookie: Cookie_2=Value2; Max-Age=78000 { "message": "Hello, world!" }`


{
   "statusCode": 201,
    "headers": {
        "Content-Type": "application/json",
        "My-Custom-Header": "Custom Value"
    },
    "body": JSON.stringify({
        "message": "Hello, world!"
    }),
    "cookies": [
        "Cookie_1=Value1; Expires=21 Oct 2021 07:48 GMT",
        "Cookie_2=Value2; Max-Age=78000"
    ],
    "isBase64Encoded": false
}


HTTP/2 201
date: Wed, 08 Sep 2021 18:02:24 GMT
content-type: application/json
content-length: 27
my-custom-header: Custom Value
set-cookie: Cookie_1=Value2; Expires=21 Oct 2021 07:48 GMT
set-cookie: Cookie_2=Value2; Max-Age=78000

{
  "message": "Hello, world!"
}

Avertissement JavaScript est désactivé ou n'est pas disponible dans votre navigateur.

Pour que vous puissiez utiliser la documentation AWS, Javascript doit être activé. Vous trouverez des instructions sur les pages d'aide de votre navigateur.

Conventions de rédaction

Contrôle d’accès

URL de fonctions de surveillance