Richiamo di URL di funzioni Lambda - AWS Lambda
Nozioni di base sul richiamo di URL di funzioniPayload di richieste e risposte

Richiamo di URL di funzioni Lambda

Un URL della funzione è un endpoint HTTP(S) dedicato alla funzione Lambda. È possibile creare e configurare un URL della funzione tramite la console Lambda o l'API Lambda.

Suggerimento

Lambda offre due modi per richiamare una funzione tramite un endpoint HTTP: URL di funzione e Amazon API Gateway. Se non sei certo del metodo più adatto al tuo caso d'uso, consultareSelezionare un metodo per richiamare la funzione Lambda tramite una richiesta HTTP.

Quando si crea un URL della funzione, Lambda genera automaticamente un endpoint URL univoco. Dopo aver creato un URL della funzione, il suo endpoint URL non cambia mai. Gli endpoint URL della funzione hanno il formato seguente:

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

Gli URL delle funzioni non sono supportati nei seguenti paesiRegioni AWS: Asia Pacifico (Hyderabad) (ap-south-2), Asia Pacifico (Melbourne) (ap-southeast-4), Asia Pacifico (Malesia) (), Asia Pacifico (Nuova Zelandaap-southeast-5) (), Asia Pacifico (Tailandia) ()ap-southeast-6, Asia Pacifico (Taipeiap-southeast-7) (), Canada occidentale (Calgary) ()ap-east-2, Europa (Spagna) ()ca-west-1, Europa (Zurigo) () eu-south-2eu-central-2, Israele (Tel Aviv) () e Medio Oriente (Emirati Arabi Uniti) (). il-central-1 me-central-1

Gli URL della funzione sono abilitati alla rete dual stack e supportano IPv4 e IPv6. Dopo aver configurato l'URL della funzione, è possibile richiamare la funzione attraverso il relativo endpoint HTTP(S) tramite un browser Web, curl, Postman o un client HTTP. Per richiamare un URL della funzione, è necessario disporre di autorizzazioni . Per ulteriori informazioni, consulta Controllo accessi.

Nozioni di base sul richiamo di URL di funzioni

Se l'URL della funzione utilizza il tipo di autenticazione AWS_IAM, è necessario firmare ogni richiesta HTTP utilizzando AWS Signature Version 4 (SigV4). Strumenti come awscurl, Postman e SigV4 Proxy offrono modalità integrate per firmare le richieste con Sigv4.

Se non utilizzi uno strumento per firmare le richieste HTTP all'URL della funzione, è necessario firmare manualmente ogni richiesta utilizzando Sigv4. Quando l'URL della funzione riceve una richiesta, Lambda calcola anche la firma Sigv4. Lambda elabora la richiesta solo se le firme corrispondono. Per le istruzioni su come firmare manualmente le richieste con SigV4, consulta Firma delle richieste AWS con Signature Version 4 nella Guida di riferimento generale di Riferimenti generali di Amazon Web Services.

Se l'URL della funzione utilizza il tipo di autenticazione NONE, non è necessario firmare le richieste utilizzando Sigv4. Puoi richiamare la funzione utilizzando un browser Web, curl, Postman o un client HTTP.

Per verificare semplici richieste GET alla funzione, usa un browser Web. Ad esempio, se l'URL della funzione è https://abcdefg.lambda-url.us-east-1.on.aws e richiede un parametro stringa message, l'URL della richiesta potrebbe essere simile al seguente:

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

Per verificare altre richieste HTTP, ad esempio una richiesta POST, puoi utilizzare uno strumento come curl. Ad esempio, se desideri includere alcuni dati JSON in una richiesta POST all'URL della funzione, potresti utilizzare il comando curl seguente:

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

Payload di richieste e risposte

Quando un client chiama l'URL della funzione, Lambda mappa la richiesta a un oggetto evento prima di passarlo alla funzione. La risposta della funzione viene quindi mappata a una risposta HTTP che Lambda invia al client tramite l'URL della funzione.

I formati degli eventi di richiesta e risposta seguono lo stesso schema del tipo di formato del payload di Gateway Amazon API versione 2.0.

Formato del payload di richiesta

Un payload di richiesta ha la seguente struttura:

{
  "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
}
Parametro Descrizione Esempio

version

Il tipo di formato del payload per questo evento. Gli URL della funzione Lambda attualmente supportano il tipo di formato del payload versione 2.0.

2.0

routeKey

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su $default come segnaposto.

$default

rawPath

Percorso della richiesta. Ad esempio, se l'URL della richiesta è https://{url-id}.lambda-url.{region}.on.aws/example/test/demo, il valore raw del percorso è /example/test/demo.

/example/test/demo

rawQueryString

La stringa raw contenente i parametri della stringa di query della richiesta. I caratteri supportati includono a-z, A-Z, 0-9, ., _, -, %, &, = e +.

"?parameter1=value1&parameter2=value2"

cookies

Un array contenente tutti i cookie inviati come parte della richiesta.

["Cookie_1=Value_1", "Cookie_2=Value_2"]

headers

L'elenco delle intestazioni della richiesta, presentate come coppie chiave-valore.

{"header1": "value1", "header2": "value2"}

queryStringParameters

I parametri di query per la richiesta. Ad esempio, se l'URL della richiesta è https://{url-id}.lambda-url.{region}.on.aws/example?name=Jane, il valore queryStringParameters è un oggetto JSON con una chiave di name e un valore di Jane.

{"name": "Jane"}

requestContext

Un oggetto contenente informazioni aggiuntive sulla richiesta, ad esempio requestId, l'ora della richiesta e l'identità del chiamante se autorizzato tramite AWS Identity and Access Management (IAM).

requestContext.accountId

L'ID Account AWS del proprietario della funzione.

"123456789012"

requestContext.apiId

L'ID dell'URL della funzione.

"33anwqw8fj"

requestContext.authentication

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su null.

null

requestContext.authorizer

Un oggetto contenente informazioni sull'identità del chiamante, se l'URL della funzione utilizza il tipo di autenticazione AWS_IAM. Altrimenti, Lambda lo imposta su null.

requestContext.authorizer.iam.accessKey

La chiave di accesso dell'identità del chiamante.

"AKIAIOSFODNN7EXAMPLE"

requestContext.authorizer.iam.accountId

L'ID Account AWS dell'identità del chiamante.

"111122223333"

requestContext.authorizer.iam.callerId

L'ID (ID utente) del chiamante.

"AIDACKCEVSQ6C2EXAMPLE"

requestContext.authorizer.iam.cognitoIdentity

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su null o lo esclude dal JSON.

null

requestContext.authorizer.iam.principalOrgId

L'ID dell'organizzazione principale associato all'identità del chiamante.

"AIDACKCEVSQORGEXAMPLE"

requestContext.authorizer.iam.userArn

L'Amazon Resource Name (ARN) utente dell'identità del chiamante.

"arn:aws:iam::111122223333:user/example-user"

requestContext.authorizer.iam.userId

L'ID utente dell'identità del chiamante.

"AIDACOSFODNN7EXAMPLE2"

requestContext.domainName

Il nome di dominio dell'URL della funzione.

"<url-id>.lambda-url.us-west-2.on.aws"

requestContext.domainPrefix

Il prefisso di dominio dell'URL della funzione.

"<url-id>"

requestContext.http

Un oggetto contenente i dettagli sulla richiesta HTTP.

requestContext.http.method

Il metodo HTTP utilizzato nella richiesta. I valori validi includono GET, POST, PUT, HEAD, OPTIONS, PATCH e DELETE.

GET

requestContext.http.path

Percorso della richiesta. Ad esempio, se l'URL della richiesta è https://{url-id}.lambda-url.{region}.on.aws/example/test/demo, il valore del percorso è /example/test/demo.

/example/test/demo

requestContext.http.protocol

Il protocollo della richiesta.

HTTP/1.1

requestContext.http.sourceIp

L'indirizzo IP di origine della connessione TCP immediata da cui proviene la richiesta.

123.123.123.123

requestContext.http.userAgent

Il valore dell'intestazione della richiesta User-Agent.

Mozilla/5.0 (Macintosh; Intel Mac OS X 10_15_7) Gecko/20100101 Firefox/42.0

requestContext.requestId

L'l'ID della richiesta di richiamo. È possibile utilizzare questo ID per tenere traccia dei registri dei richiami correlati alla funzione.

e1506fd5-9e7b-434f-bd42-4f8fa224b599

requestContext.routeKey

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su $default come segnaposto.

$default

requestContext.stage

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su $default come segnaposto.

$default

requestContext.time

Il timestamp della richiesta.

"07/Sep/2021:22:50:22 +0000"

requestContext.timeEpoch

Il timestamp della richiesta, in formato temporale Unix epoch.

"1631055022677"

body

Il corpo della richiesta. Se il tipo di contenuto della richiesta è binario, il corpo è con codifica base64.

{"key1": "value1", "key2": "value2"}

pathParameters

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su null o lo esclude dal JSON.

null

isBase64Encoded

TRUE se il corpo è un payload binario e con codifica base64. FALSE in caso contrario.

FALSE

stageVariables

Gli URL della funzione non utilizzano questo parametro. Lambda lo imposta su null o lo esclude dal JSON.

null

Formato del payload di risposta

Quando la funzione restituisce una risposta, Lambda analizza la risposta e la converte in una risposta HTTP. I payload di risposta della funzione hanno il formato seguente:

{
   "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 deduce il formato di risposta per l'utente. Se la funzione Lambda restituisce un JSON valido e non restituisce un statusCode, Lambda presuppone quanto segue:

  • statusCode is 200.

    Nota

    I valori validi statusCode sono compresi tra 100 e 599.

  • content-type is application/json.

  • body è la risposta della funzione.

  • isBase64Encoded is false.

Gli esempi seguenti mostrano come l'output della funzione Lambda viene mappato al payload della risposta e come il payload della risposta viene mappato alla risposta HTTP finale. Quando il client richiama l'URL della funzione, viene visualizzata la risposta HTTP.

Esempio di output per una risposta stringa

Risultato della funzione Lambda Output di risposta interpretata Risposta HTTP (cosa vede il 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!"

Esempio di output per una risposta JSON

Risultato della funzione Lambda Output di risposta interpretata Risposta HTTP (cosa vede il 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!"
}

Esempio di output per una risposta personalizzata

Risultato della funzione Lambda Output di risposta interpretata Risposta HTTP (cosa vede il 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!"
}

Cookie

Per restituire i cookie della funzione, non aggiungere manualmente intestazioni set-cookie. Al contrario, includi i cookie nell'oggetto payload di risposta. Lambda li interpreta automaticamente e li aggiunge come intestazioni set-cookie nella risposta HTTP, come nell'esempio seguente.

Risultato della funzione Lambda Risposta HTTP (cosa vede il 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!"
}