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.
-
La pagina dei concetti di Amazon API Gateway.
-
Scegliere tra HTTP APIs e REST APIs nella guida per sviluppatori di API Gateway.
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.rproxy.goskope.comL'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
orString
-
Il corpo della richiesta HTTP. Il suo tipo può essere un
JSON
oggetto oString
.RequestBody
è supportato solo perPATCH
i metodiPUT
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 nonAllowNullValues
sia impostato sutrue
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 macchinaAllowNullValues
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:
-
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.
-
That Step Functions è il servizio che chiama API Gateway:
"Service": "states.amazonaws.com"
. -
La risorsa a cui desideri accedere, tra cui:
-
Tipo
region
. -
account-id
Nella 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 formato
ApiGateway.
.<HTTP Status Code>
-
Se il codice di stato HTTP non è disponibile, l'errore verrà restituito nel formato
ApiGateway.
.<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>
"
]
}
}
}
]
}