Supporto della funzionalità API Gateway Formato della richiesta Autenticazione e autorizzazione Modelli di integrazione dei servizi Formato di output Gestione degli errori

Chiama API Gateway con Step Functions

Step Functions può controllare determinati AWS servizi direttamente da Amazon States Language (ASL). Per ulteriori informazioni, consultare Uso di altri servizi e Passa i parametri a un'API di servizio.

In che modo l'integrazione Optimized API Gateway è diversa dall'integrazione con API Gateway AWS SDK

apigateway:invoke:non ha equivalenti nell'integrazione del servizio AWS SDK. Invece, il servizio Optimized API Gateway chiama direttamente l'endpoint API Gateway.

Utilizzi Amazon API Gateway per creare, pubblicare, gestire e monitorare le API HTTP e REST. 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.

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 API ottimizzate per Edge 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 le relative API HTTP e REST, consulta quanto segue.

La pagina dei concetti di Amazon API Gateway.
Scelta tra API HTTP e API REST nella guida per sviluppatori di API Gateway.

Formato della richiesta

Quando crei 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, 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. In caso contrario, verrà concesso l'accesso a qualsiasi macchina a stati che autentica la sua richiesta API Gateway con l'autenticazione delle policy delle risorse sulla vostra API.
2. That Step Functions è il servizio che chiama API Gateway:"Service": "states.amazonaws.com".
3. La risorsa a cui desideri accedere, tra cui:
  - La regione.
  - L'ID dell'account nella regione specificata.
  - L'api-id.
  - Il nome d'arte.
  - Il metodo HTTP-VERB ().
  - L'identificatore del percorso di risorsa.
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.

Attendere un callback con il token dell’attività(.waitForTaskToken), che attende la restituzione di un task token con un payload. Per utilizzare lo .waitForTaskToken schema, aggiungi .wait ForTaskToken alla fine del campo Resource 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	Type	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.

Per ulteriori informazioni, consulta la pagina:

Concetti di Amazon API Gateway nella API Gateway Developer Guide.
Politiche IAM per Amazon API Gateway
Un progetto di esempio che mostra come Effettuare una chiamata a API Gateway

Concetti di Amazon API Gateway nella API Gateway Developer Guide.

Avvertimento JavaScript è disabilitato o non è disponibile nel tuo browser.

Per usare la documentazione AWS, JavaScript deve essere abilitato. Consulta le pagine della guida del browser per le istruzioni.

Convenzioni dei documenti

Integrazioni ottimizzate

Amazon Athena

Chiama API Gateway con Step Functions

In che modo l'integrazione Optimized API Gateway è diversa dall'integrazione con API Gateway AWS SDK

Supporto della funzionalità API Gateway

Formato della richiesta

Parametri di richiesta obbligatori

Parametri di richiesta opzionali

Nota

Nota

Autenticazione e autorizzazione

Importante

Nota

Modelli di integrazione dei servizi

Formato di output

Gestione degli errori

Nota