Crea API Gateway REST APIs con Step Functions - AWS Step Functions

Le traduzioni sono generate tramite traduzione automatica. In caso di conflitto tra il contenuto di una traduzione e la versione originale in Inglese, quest'ultima prevarrà.

Crea API Gateway REST APIs con Step Functions

Scopri come usare Amazon API Gateway per creare, pubblicare, gestire e monitorare HTTP e REST APIs con Step Functions. Per l'integrazione con API Gateway, definisci uno Task stato in Step Functions che richiama direttamente un endpoint API Gateway HTTP o API Gateway REST, senza scrivere codice o fare affidamento su altre infrastrutture. Una definizione di Task stato include tutte le informazioni necessarie per la chiamata API. È inoltre possibile selezionare diversi metodi di autorizzazione.

Per ulteriori informazioni sull'integrazione con AWS i servizi in Step Functions, vedere Integrazione dei servizi ePassaggio di parametri a un'API di servizio in Step Functions.

Caratteristiche principali dell'integrazione con Optimized API Gateway
  • apigateway:invoke:non ha equivalenti nell'integrazione dei servizi AWS SDK. Invece, il servizio Optimized API Gateway chiama direttamente l'endpoint API Gateway.

Supporto della funzionalità API Gateway

L'integrazione di Step Functions API Gateway supporta alcune funzionalità di API Gateway, ma non tutte. Per un elenco più dettagliato delle funzionalità supportate, consulta quanto segue.

  • Supportato dalle integrazioni API REST di Step Functions API Gateway e API Gateway HTTP:

    • Autorizzatori: IAM (utilizzando Signature Version 4), No Auth, Lambda Authorizers (basati su parametri di richiesta e basati su token con intestazione personalizzata)

    • Tipi di API: regionali

    • Gestione delle API: nomi di dominio API Gateway API, fase dell'API, percorso, parametri di interrogazione, corpo della richiesta

  • Supportato dall'integrazione dell'API HTTP Step Functions API Gateway. L'integrazione dell'API REST di Step Functions API Gateway che offre l'opzione per l'ottimizzazione per Edge APIs non è supportata.

  • Non supportato dall'integrazione con Step Functions API Gateway:

    • Autorizzatori: Amazon Cognito, Native Open ID Connect OAuth /2.0, intestazione di autorizzazione per autorizzatori Lambda basati su token

    • Tipi di API: private

    • Gestione delle API: nomi di dominio personalizzati

Per ulteriori informazioni su API Gateway e i relativi HTTP e REST APIs, consulta quanto segue.

Formato della richiesta

Quando create la definizione Task dello stato, Step Functions convalida i parametri, crea l'URL necessario per eseguire la chiamata, quindi chiama l'API. La risposta include il codice di stato HTTP, le intestazioni e il corpo della risposta. Il formato della richiesta ha parametri obbligatori e facoltativi.

Parametri di richiesta obbligatori

  • ApiEndpoint

    • Tipo: String

    • Il nome host di un URL API Gateway. Il formato è <API ID>.execute-api.<region>.amazonaws.com.

      L'ID API può contenere solo una combinazione dei seguenti caratteri alfanumerici: 0123456789abcdefghijklmnopqrstuvwxyz

  • Method

    • Tipo: Enum

    • Il metodo HTTP, che deve essere uno dei seguenti:

      • GET

      • POST

      • PUT

      • DELETE

      • PATCH

      • HEAD

      • OPTIONS

Parametri di richiesta opzionali

  • Headers

    • Tipo: JSON

    • Le intestazioni HTTP consentono un elenco di valori associati alla stessa chiave.

  • Stage

    • Tipo: String

    • Il nome della fase in cui viene distribuita l'API in API Gateway. È facoltativo per qualsiasi API HTTP che utilizza lo $default stage.

  • Path

    • Tipo: String

    • Parametri di percorso che vengono aggiunti dopo l'endpoint dell'API.

  • QueryParameters

    • Tipo: JSON

    • Le stringhe di query consentono solo un elenco di valori associati alla stessa chiave.

  • RequestBody

    • Tipo: JSON or String

    • Il corpo della richiesta HTTP. Il suo tipo può essere un JSON oggetto oString. RequestBodyè supportato solo per PATCH i metodi PUT HTTPPOST, e.

  • AllowNullValues

    • Tipo: BOOLEAN — valore predefinito: false

    • Con l'impostazione predefinita, tutti i valori nulli nello stato di input della richiesta non verranno inviati all'API. Nell'esempio seguente, il category campo non verrà incluso nella richiesta, a meno che non AllowNullValues sia impostato su true nella definizione della macchina a stati.

      { "NewPet": { "type": "turtle", "price": 123, "category": null } }
      Nota

      Per impostazione predefinita, i campi con valori nulli nello stato di input della richiesta non verranno inviati all'API. Puoi forzare l'invio di valori nulli all'API impostando su true nella definizione della macchina AllowNullValues a stati.

  • AuthType

    • Tipo: JSON

    • Il metodo di autenticazione. Il metodo predefinito èNO_AUTH. I valori consentiti sono:

      • NO_AUTH

      • IAM_ROLE

      • RESOURCE_POLICY

      Per ulteriori informazioni, vedere Autenticazione e autorizzazione.

Nota

Per motivi di sicurezza, le seguenti chiavi di intestazione HTTP non sono attualmente consentite:

  • Qualsiasi cosa preceduta da, o. X-Forwarded X-Amz X-Amzn

  • Authorization

  • Connection

  • Content-md5

  • Expect

  • Host

  • Max-Forwards

  • Proxy-Authenticate

  • Server

  • TE

  • Transfer-Encoding

  • Trailer

  • Upgrade

  • Via

  • Www-Authenticate

Il seguente esempio di codice mostra come richiamare API Gateway utilizzando Step Functions.

{ "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "GET", "Headers": { "key": ["value1", "value2"] }, "Stage": "prod", "Path": "bills", "QueryParameters": { "billId": ["123456"] }, "RequestBody": {}, "AuthType": "NO_AUTH" } }

Autenticazione e autorizzazione

È possibile utilizzare i seguenti metodi di autenticazione:

  • Nessuna autorizzazione: chiama l'API direttamente senza alcun metodo di autorizzazione.

  • Ruolo IAM: con questo metodo, Step Functions assume il ruolo di macchina a stati, firma la richiesta con Signature Version 4 (SigV4), quindi chiama l'API.

  • Politica delle risorse: Step Functions autentica la richiesta e quindi chiama l'API. È necessario allegare una politica delle risorse all'API che specifichi quanto segue:

    1. La macchina a stati che invocherà API Gateway.

      Importante

      È necessario specificare la macchina a stati per limitarne l'accesso. Se non lo fai, verrà concesso l'accesso a qualsiasi macchina a stati che autentica la sua richiesta API Gateway con l'autenticazione delle policy delle risorse sulla tua API.

    2. That Step Functions è il servizio che chiama API Gateway:"Service": "states.amazonaws.com".

    3. La risorsa a cui desideri accedere, tra cui:

      • Tipo region.

      • account-idNella regione specificata.

      • Tipo api-id.

      • Tipo stage-name.

      • Il HTTP-VERB (metodo).

      • Tipo resource-path-specifier.

    Per un esempio di politica delle risorse, consulta le politiche IAM per Step Functions e API Gateway.

    Per ulteriori informazioni sul formato delle risorse, consulta Formato delle risorse delle autorizzazioni per l'esecuzione dell'API in API Gateway nella Guida per sviluppatori di API Gateway.

    Nota

    Le policy relative alle risorse sono supportate solo per l'API REST.

Modelli di integrazione dei servizi

L'integrazione con API Gateway supporta due modelli di integrazione dei servizi:

  • Richiesta e risposta, che è il modello di integrazione predefinito. Consente a Step Functions di passare alla fase successiva immediatamente dopo aver ricevuto una risposta HTTP.

  • Attendi una richiamata con Task Token(.waitForTaskToken), che attende la restituzione di un task token con un payload. Per usare il .waitForTaskToken pattern, aggiungi. waitForTaskSimbolo alla fine del campo Risorsa della definizione dell'attività, come mostrato nell'esempio seguente:

    { "Type": "Task", "Resource":"arn:aws:states:::apigateway:invoke.waitForTaskToken", "Parameters": { "ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com", "Method": "POST", "Headers": { "TaskToken.$": "States.Array($$.Task.Token)" }, "Stage": "prod", "Path": "bills/add", "QueryParameters": {}, "RequestBody": { "billId": "my-new-bill" }, "AuthType": "IAM_ROLE" } }

Formato di output

Vengono forniti i seguenti parametri di output:

Nome Tipo Descrizione
ResponseBody JSON o String Il corpo della risposta della chiamata API.
Headers JSON Le intestazioni di risposta.
StatusCode Integer Il codice di stato HTTP per la risposta.
StatusText String Il testo dello stato della risposta.

Un esempio di risposta:

{ "ResponseBody": { "myBills": [] }, "Headers": { "key": ["value1", "value2"] }, "StatusCode": 200, "StatusText": "OK" }

Gestione degli errori

Quando si verifica un errore, cause viene restituito un error and come segue:

  • Se il codice di stato HTTP è disponibile, l'errore verrà restituito nel formatoApiGateway.<HTTP Status Code>.

  • Se il codice di stato HTTP non è disponibile, l'errore verrà restituito nel formatoApiGateway.<Exception>.

In entrambi i casi, cause viene restituito come stringa.

L'esempio seguente mostra una risposta in cui si è verificato un errore:

{ "error": "ApiGateway.403", "cause": "{\"message\":\"Missing Authentication Token\"}" }
Nota

Un codice di stato 2XX indica l'esito positivo e non verrà restituito alcun errore. Tutti gli altri codici di stato o le eccezioni generate genereranno un errore.

Politiche IAM per le chiamate verso Amazon API Gateway

I seguenti modelli di esempio mostrano come AWS Step Functions generare le politiche IAM in base alle risorse nella definizione della macchina a stati. Per ulteriori informazioni, consulta In che modo Step Functions genera policy IAM per servizi integrati e Scopri i modelli di integrazione dei servizi in Step Functions.

Risorse:

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Action": [ "execute-api:Invoke" ], "Resource": [ "arn:[[region]]:[[accountId]]:*" ] } ] }

Il seguente esempio di codice mostra una politica delle risorse per chiamare API Gateway.

{ "Version": "2012-10-17", "Statement": [ { "Effect": "Allow", "Principal": { "Service": "states.amazonaws.com" }, "Action": "execute-api:Invoke", "Resource": "arn:aws:execute-api:<region>:<account-id>:<api-id>/<stage-name>/<HTTP-VERB>/<resource-path-specifier>", "Condition": { "StringEquals": { "aws:SourceArn": [ "<SourceStateMachineArn>" ] } } } ] }