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 ](integrate-services.md) e[Passaggio di parametri a un'API di servizio in Step Functions](connect-parameters.md).
**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](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html)), 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](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-basic-concept.html).
+ [Scegliere tra HTTP APIs e REST APIs](https://docs.aws.amazon.com/apigateway/latest/developerguide/http-api-vs-rest.html) 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 è `.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 o`String`. `RequestBody`è supportato solo per `PATCH` i metodi `PUT` HTTP`POST`, 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",
"Arguments": {
"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](https://docs.aws.amazon.com/general/latest/gr/sigv4_signing.html) (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.
1. That Step Functions è il servizio che chiama API Gateway:`"Service": "states.amazonaws.com"`.
1. 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](#api-gateway-iam).
Per ulteriori informazioni sul formato delle risorse, consulta [Formato delle risorse delle autorizzazioni per l'esecuzione dell'API in API Gateway nella](https://docs.aws.amazon.com/apigateway/latest/developerguide/api-gateway-control-access-using-iam-policies-to-invoke-api.html#api-gateway-iam-policy-resource-format-for-executing-api) 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](connect-to-resource.md#connect-default), 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](connect-to-resource.md#connect-wait-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",
"Arguments": {
"ApiEndpoint": "example.execute-api.us-east-1.amazonaws.com",
"Method": "POST",
"Headers": {
"TaskToken": "{% $states.context.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:
| Name | Tipo | Description |
| --- | --- | --- |
| 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.`.
+ Se il codice di stato HTTP non è disponibile, l'errore verrà restituito nel formato`ApiGateway.`.
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, consultare [In che modo Step Functions genera policy IAM per servizi integrati](service-integration-iam-templates.md) e [Scopri i modelli di integrazione dei servizi in Step Functions](connect-to-resource.md).
*Risorse:*
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Action": [
"execute-api:Invoke"
],
"Resource": [
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/GET/pets",
"arn:aws:execute-api:us-east-1:123456789012:ENDPOINT/STAGE/POST/pets"
],
"Effect": "Allow"
}
]
}
```
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:us-east-1:123456789012:myApi-id/stage-name/HTTP-VERB/resource-path-specifier",
"Condition": {
"StringEquals": {
"aws:SourceArn": [
""
]
}
}
}
]
}
```