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à.
# Chiama HTTPS APIs nei flussi di lavoro Step Functions
Un task HTTP è un tipo di [Stato del flusso di lavoro delle attività](state-task.md) stato che puoi usare per chiamare HTTPS APIs nei tuoi flussi di lavoro. L'API può essere pubblica, ad esempio applicazioni SaaS di terze parti come Stripe o Salesforce. Puoi anche chiamare API private, ad esempio applicazioni basate su HTTPS in un Amazon Virtual Private Cloud.
Per l'autorizzazione e la connettività di rete, un Task HTTP richiede una EventBridge connessione.
Per chiamare un'API HTTPS, utilizza lo stato [Task](state-task.md) con la `arn:aws:states:::http:invoke` risorsa. Quindi, fornisci i dettagli di configurazione dell'endpoint dell'API, come l'URL dell'API, il metodo che desideri utilizzare e i dettagli di [connessione](#http-task-authentication).
Se utilizzate [Workflow Studio](workflow-studio.md) per creare una macchina a stati che contiene un task HTTP, Workflow Studio genera automaticamente un ruolo di esecuzione con IAM politiche per il task HTTP. Per ulteriori informazioni, consulta [Ruolo per il test delle attività HTTP in Workflow Studio](manage-state-machine-permissions.md#test-state-role-http).
**Nota**
HTTP Task attualmente supporta solo nomi di dominio pubblico con certificati pubblicamente affidabili per endpoint HTTPS quando si utilizza il formato privato APIs. HTTP Task non supporta il TLS reciproco (MTL).
**Topics**
+ [
## Connettività per un task HTTP
](#http-task-authentication)
+ [
## Definizione del task HTTP
](#connect-http-task-definition)
+ [
## Campi HTTP Task
](#connect-http-task-fields)
+ [
## Unione dei dati di EventBridge connessione e di definizione dell'attività HTTP
](#http-task-data-merge)
+ [
## Applicazione della codifica URL nel corpo della richiesta
](#url-encode-request-body)
+ [
## Autorizzazioni IAM per eseguire un task HTTP
](#connect-http-task-permissions)
+ [
## Esempio di attività HTTP
](#connect-http-task-example)
+ [
## Test di un task HTTP
](#http-task-test)
+ [
## Risposte HTTP Task non supportate
](#unsupported-http-task-responses)
+ [Errori di connessione](#connect-http-task-errors)
## Connettività per un task HTTP
Un task HTTP richiede una [EventBridgeconnessione](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), che gestisce in modo sicuro le credenziali di autenticazione di un provider di API. Una *connessione* definisce il metodo di autorizzazione e le credenziali da utilizzare per la connessione a una determinata API. Se ti connetti a un'API privata, ad esempio un'API privata in un Amazon Virtual Private Cloud (Amazon VPC), puoi anche utilizzare la connessione per definire una connettività di point-to-point rete sicura. L'utilizzo di una connessione consente di evitare l'inserimento di segreti a codifica fissa, come le chiavi API, nella definizione della macchina a stati. Una EventBridge connessione supporta gli schemi di autorizzazione Basic e API Key. OAuth
Quando si crea una EventBridge connessione, si forniscono i dettagli relativi all'autorizzazione e alla connettività di rete. Puoi anche includere i parametri header, body e query necessari per l'autorizzazione con un'API. È necessario includere l'ARN della connessione in qualsiasi attività HTTP che richiama un'API HTTPS.
Quando crei una connessione, EventBridge crea un indirizzo [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) in Gestione dei segreti AWS. In questo segreto, EventBridge memorizza i parametri di connessione e autorizzazione in forma crittografata. Per creare o aggiornare correttamente una connessione, è necessario utilizzare un Account AWS utente autorizzato a utilizzare Secrets Manager. Per ulteriori informazioni sulle IAM autorizzazioni necessarie alla macchina a stati per accedere a una EventBridge connessione, vedere[Autorizzazioni IAM per eseguire un task HTTP](#connect-http-task-permissions).
L'immagine seguente mostra come Step Functions gestisce l'autorizzazione per le chiamate API HTTPS utilizzando una EventBridge connessione. La EventBridge connessione gestisce le credenziali di un provider di API HTTPS. EventBridgecrea un indirizzo [https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html](https://docs.aws.amazon.com/secretsmanager/latest/userguide/managing-secrets.html) Secrets Manager per memorizzare i parametri di connessione e autorizzazione in forma crittografata. Nel caso di dati privati APIs, memorizza EventBridge anche le configurazioni di connettività di rete.
**Timeout per le connessioni**
Le richieste di attività HTTP scadranno dopo 60 secondi.
![\[Step Functions utilizza l'autorizzazione e la configurazione di rete nelle EventBridge connessioni per le chiamate agli endpoint HTTPS.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/connections-overview_step-functions_conceptual.png)
## Definizione del task HTTP
La [definizione ASL](concepts-amazon-states-language.md) rappresenta un task HTTP con `http:invoke` risorsa. La seguente definizione di HTTP Task richiama un'API Stripe pubblica che restituisce un elenco di tutti i clienti.
```
"Call HTTPS API": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"ApiEndpoint": "https://api.stripe.com/v1/customers",
"Authentication": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"Method": "GET"
},
"End": true
}
```
## Campi HTTP Task
Un task HTTP include i seguenti campi nella sua definizione.
**`Resource` (Obbligatorio)**
Per specificare un [tipo di attività](state-task.md#task-types), inserisci il relativo ARN nel `Resource` campo. Per un task HTTP, si specifica il `Resource` campo come segue.
```
"Resource": "arn:aws:states:::http:invoke"
```
**`Parameters` (Obbligatorio)**
Contiene i `ConnectionArn` campi `ApiEndpoint``Method`, e che forniscono informazioni sull'API HTTPS da chiamare. `Parameters`contiene anche campi opzionali, come `Headers` e`QueryParameters`.
È possibile specificare una combinazione di JSON statico e [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintassi come `Parameters` nel `Parameters` campo. Per ulteriori informazioni, consulta [Passaggio di parametri a un'API di servizio in Step Functions](connect-parameters.md).
Per specificare la EventBridge connessione, utilizzare il campo `Authentication` *o*`InvocationConfig`.
`ApiEndpoint`**(Obbligatorio)**
Speciifica l'URL dell'API HTTPS che desideri chiamare. Per aggiungere parametri di query all'URL, utilizza il `QueryParameters` campo. L'esempio seguente mostra come chiamare un'API Stripe per recuperare l'elenco di tutti i clienti.
```
"ApiEndpoint":"https://api.stripe.com/v1/customers"
```
Puoi anche specificare un [percorso di riferimento](amazon-states-language-paths.md#amazon-states-language-reference-paths) utilizzando la [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintassi per selezionare il nodo JSON che contiene l'URL dell'API HTTPS. Ad esempio, supponiamo che tu voglia chiamare uno di Stripe APIs utilizzando un ID cliente specifico. Immagina di aver fornito il seguente input di stato.
```
{
"customer_id": "1234567890",
"name": "John Doe"
}
```
Per recuperare i dettagli di questo ID cliente utilizzando un'API Stripe, specifica `ApiEndpoint` come mostrato nell'esempio seguente. Questo esempio utilizza una [funzione intrinseca](intrinsic-functions.md) e un percorso di riferimento.
```
"ApiEndpoint.$":"States.Format('https://api.stripe.com/v1/customers/{}', $.customer_id)"
```
In fase di esecuzione, Step Functions risolve il valore di `ApiEndpoint` come segue.
```
https://api.stripe.com/v1/customers/1234567890
```
`Method`**(Obbligatorio)**
Speciifica il metodo HTTP che desideri utilizzare per chiamare un'API HTTPS. È possibile specificare uno di questi metodi nel task HTTP: GET, POST, PUT, DELETE, PATCH, OPTIONS o HEAD.
Ad esempio, per utilizzare il metodo GET, specificate il `Method` campo come segue.
```
"Method": "GET"
```
È inoltre possibile utilizzare un [percorso di riferimento](amazon-states-language-paths.md#amazon-states-language-reference-paths) per specificare il metodo in fase di esecuzione. Ad esempio, **"Method.\$1": "\$1.myHTTPMethod"**.
`Authentication`**(Condizionale)**
*Ti consigliamo di utilizzare `InvocationConfig` over `Authentication` per le chiamate API HTTPS pubbliche e private.*
`Authentication`I riferimenti esistenti vengono mantenuti per garantire la compatibilità con le versioni precedenti. All'interno del campo, è necessario specificare un `ConnectionArn` campo che specifichi una risorsa di connessione Amazon EventBridge a cui connettersi a. `ApiEndpoint`
`InvocationConfig`**(Condizionale)**
Contiene l'autorizzazione e la configurazione della connettività di rete per **le** chiamate API HTTPS pubbliche e private.
Step Functionsgestisce la connessione per una determinata area `ApiEndpoint` utilizzando la risorsa di connessione diAmazon EventBridge. Per ulteriori informazioni, consulta [Connecting to private APIs](https://docs.aws.amazon.com/eventbridge/latest/userguide/connection-private.html) nella *Amazon EventBridge User Guide*.
`ConnectionArn`**(Richiesto)**
Speciifica l'ARN della EventBridge connessione.
Un task HTTP richiede una [EventBridge connessione](https://docs.aws.amazon.com/eventbridge/latest/userguide/eb-target-connection.html), che gestisce in modo sicuro le credenziali di autorizzazione di un provider di API. Una *connessione* specifica il tipo di autorizzazione e le credenziali da utilizzare per autorizzare un'API HTTPS. Per uso privato APIs, la connessione definisce anche una connettività di rete sicura point-to-point. L'utilizzo di una connessione consente di evitare l'inserimento di segreti a codifica fissa, come le chiavi API, nella definizione della macchina a stati. In una connessione, puoi anche specificare `Headers``QueryParameters`, e `RequestBody` parametri.
Per ulteriori informazioni, consulta [Connettività per un task HTTP](#http-task-authentication).
L'esempio seguente mostra il formato di `InvocationConfig` in un task HTTP:
```
"InvocationConfig": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/connection-id"
}
```
`Headers` (facoltativo).
Fornisce contesto e metadati aggiuntivi all'endpoint dell'API. È possibile specificare le intestazioni come stringa o array JSON.
È possibile specificare le intestazioni nella EventBridge connessione e nel `Headers` campo in un task HTTP. Ti consigliamo di non includere nel `Headers` campo i dettagli di autenticazione dei tuoi provider di API. Ti consigliamo di includere questi dettagli nella tua EventBridge connessione.
Step Functionsaggiunge le intestazioni specificate nella EventBridge connessione alle intestazioni specificate nella definizione del task HTTP. Se nella definizione e nella connessione sono presenti le stesse chiavi di intestazione, Step Functions utilizza i valori corrispondenti specificati nella EventBridge connessione per tali intestazioni. Per ulteriori informazioni su come Step Functions esegue l'unione dei dati, vedere. [Unione dei dati di EventBridge connessione e di definizione dell'attività HTTP](#http-task-data-merge)
L'esempio seguente specifica un'intestazione che verrà inclusa in una chiamata API HTTPS:. `content-type`
```
"Headers": {
"content-type": "application/json"
}
```
È inoltre possibile utilizzare un [percorso di riferimento](amazon-states-language-paths.md#amazon-states-language-reference-paths) per specificare le intestazioni in fase di esecuzione. Ad esempio, **"Headers.\$1": "\$1.myHTTPHeaders"**.
Step Functionsimposta le `Host` intestazioni `User-Agent``Range`, e. Step Functionsimposta il valore dell'`Host`intestazione in base all'API che stai chiamando. Di seguito è riportato un esempio di queste intestazioni.
```
User-Agent: Amazon|StepFunctions|HttpInvoke|region,
Range: bytes=0-262144,
Host: api.stripe.com
```
Non è possibile utilizzare le seguenti intestazioni nella definizione del task HTTP. Se si utilizzano queste intestazioni, il task HTTP ha esito negativo e viene visualizzato l'`States.Runtime`errore.
+ A-IM
+ Accept-Charset
+ Accept-Datetime
+ Accept-Encoding
+ Autorizzazione
+ Cache-Control
+ Connessione
+ Content-Encoding
+ Contenuto- MD5
+ Data
+ Expect
+ Forwarded
+ Da
+ Host
+ HTTP2-Impostazioni
+ If-Match
+ If-Modified-Since
+ If-None-Match
+ If-Range
+ If-Unmodified-Since
+ Max-Forwards
+ Origin
+ Pragma
+ Proxy-Authorization
+ Referente
+ Server
+ TE
+ Trailer
+ Transfer-Encoding
+ Upgrade
+ Via
+ Attenzione
+ x-forwarded-\$1
+ x-amz-\$1
+ x-amzn-\$1
`QueryParameters` (facoltativo).
Inserisce coppie chiave-valore alla fine di un URL API. È possibile specificare i parametri di query come stringa, array JSON o oggetto JSON. Step Functionsl'URL codifica automaticamente i parametri di interrogazione quando richiama un'API HTTPS.
Ad esempio, supponiamo di voler chiamare l'API Stripe per cercare clienti che effettuano transazioni in dollari USA (USD). Immagina di aver fornito quanto segue `QueryParameters` come input di stato.
```
"QueryParameters": {
"currency": "usd"
}
```
In fase di esecuzione, Step Functions aggiunge `QueryParameters` all'URL dell'API come segue.
```
https://api.stripe.com/v1/customers/search?currency=usd
```
È inoltre possibile utilizzare un [percorso di riferimento](amazon-states-language-paths.md#amazon-states-language-reference-paths) per specificare i parametri della query in fase di esecuzione. Ad esempio, **"QueryParameters.\$1": "\$1.myQueryParameters"**.
Se hai specificato i parametri di query nella EventBridge connessione, Step Functions aggiunge questi parametri di query ai parametri di query specificati nella definizione del task HTTP. Se nella definizione e nella connessione sono presenti le stesse chiavi dei parametri di query, Step Functions utilizza i valori corrispondenti specificati nella EventBridge connessione per tali intestazioni. Per ulteriori informazioni su come Step Functions esegue l'unione dei dati, vedere. [Unione dei dati di EventBridge connessione e di definizione dell'attività HTTP](#http-task-data-merge)
`Transform` (facoltativo).
Contiene i `RequestEncodingOptions` campi `RequestBodyEncoding` e. Per impostazione predefinita, Step Functions invia il corpo della richiesta come dati JSON a un endpoint API.
Se il tuo provider di API accetta i corpi delle `form-urlencoded` richieste, utilizza il `Transform` campo per specificare la codifica URL per i corpi della richiesta. È inoltre necessario specificare l'intestazione come. `content-type` `application/x-www-form-urlencoded` Step Functionsquindi codifica automaticamente l'URL del corpo della richiesta.
`RequestBodyEncoding`
Speciifica la codifica URL del corpo della richiesta. È possibile specificare uno di questi valori: o. `NONE` `URL_ENCODED`
+ `NONE`— Il corpo della richiesta HTTP sarà il codice JSON serializzato del `RequestBody` campo. Si tratta del valore di default.
+ `URL_ENCODED`— Il corpo della richiesta HTTP sarà costituito dai dati del modulo con codifica URL del campo. `RequestBody`
`RequestEncodingOptions`
Determina l'opzione di codifica da utilizzare per gli array nel corpo della richiesta, se impostata su. `RequestBodyEncoding` `URL_ENCODED`
Step Functionssupporta le seguenti opzioni di codifica degli array. Per ulteriori informazioni su queste opzioni e sui relativi esempi, vedere[Applicazione della codifica URL nel corpo della richiesta](#url-encode-request-body).
+ `INDICES`— Codifica gli array utilizzando il valore di indice degli elementi dell'array. Per impostazione predefinita, Step Functions utilizza questa opzione di codifica.
+ `REPEAT`— Ripete una chiave per ogni elemento di un array.
+ `COMMAS`— Codifica tutti i valori di una chiave come elenco di valori delimitato da virgole.
+ `BRACKETS`— Ripete una chiave per ogni elemento di una matrice e aggiunge una parentesi, [], alla chiave per indicare che si tratta di una matrice.
L'esempio seguente imposta la codifica URL per i dati del corpo della richiesta. Specifica inoltre di utilizzare l'opzione di `COMMAS` codifica per gli array nel corpo della richiesta.
```
"Transform": {
"RequestBodyEncoding": "URL_ENCODED",
"RequestEncodingOptions": {
"ArrayFormat": "COMMAS"
}
}
```
`RequestBody` (facoltativo).
Accetta i dati JSON forniti nell'input dello stato. In`RequestBody`, puoi specificare una combinazione di JSON statico e [JsonPath](https://datatracker.ietf.org/wg/jsonpath/about/)sintassi. Ad esempio, supponiamo di fornire il seguente input di stato:
```
{
"CardNumber": "1234567890",
"ExpiryDate": "09/25"
}
```
Per utilizzare questi valori di `CardNumber` e `ExpiryDate` nel corpo della richiesta in fase di esecuzione, puoi specificare i seguenti dati JSON nel corpo della richiesta.
```
"RequestBody": {
"Card": {
"Number.$": "$.CardNumber",
"Expiry.$": "$.ExpiryDate",
"Name": "John Doe",
"Address": "123 Any Street, Any Town, USA"
}
}
```
Se l'API HTTPS che desideri chiamare richiede corpi di `form-urlencoded` richiesta, devi specificare la codifica URL per i dati del corpo della richiesta. Per ulteriori informazioni, consulta [Applicazione della codifica URL nel corpo della richiesta](#url-encode-request-body).
## Unione dei dati di EventBridge connessione e di definizione dell'attività HTTP
Quando si richiama un task HTTP, è possibile specificare i dati nella EventBridge connessione e nella definizione del task HTTP. Questi dati includono `Headers` `QueryParameters` e `RequestBody` parametri. Prima di chiamare un'API HTTPS, Step Functions unisce il corpo della richiesta con i parametri del corpo della connessione in tutti i casi, tranne se il corpo della richiesta è una stringa e i parametri del corpo di connessione non sono vuoti. In questo caso, il task HTTP ha esito negativo e restituisce l'`States.Runtime`errore.
Se sono presenti chiavi duplicate specificate nella definizione del task HTTP e nella EventBridge connessione, Step Functions sovrascrive i valori del task HTTP con i valori della connessione.
L'elenco seguente descrive come Step Functions unire i dati prima di chiamare un'API HTTPS:
+ **Intestazioni**: Step Functions aggiunge le intestazioni specificate nella connessione alle intestazioni nel `Headers` campo dell'attività HTTP. In caso di conflitto tra le chiavi di intestazione, Step Functions utilizza i valori specificati nella connessione per tali intestazioni. Ad esempio, se hai specificato l'`content-type`intestazione sia nella definizione del task HTTP che nella EventBridge connessione, Step Functions utilizza il valore dell'`content-type`intestazione specificato nella connessione.
+ **Parametri** di query: Step Functions aggiunge tutti i parametri di query specificati nella connessione ai parametri di query nel `QueryParameters` campo del task HTTP. In caso di conflitto tra le chiavi dei parametri di query, Step Functions utilizza i valori specificati nella connessione per tali parametri di query. Ad esempio, se hai specificato il parametro di `maxItems` query sia nella definizione del task HTTP che nella EventBridge connessione, Step Functions utilizza il valore del parametro di `maxItems` query specificato nella connessione.
+ **Parametri corpo**
+ Step Functionsaggiunge tutti i valori del corpo della richiesta specificati nella connessione al corpo della richiesta nel `RequestBody` campo del task HTTP. In caso di conflitto tra le chiavi del corpo della richiesta, Step Functions utilizza i valori specificati nella connessione per il corpo della richiesta. Ad esempio, supponiamo di aver specificato un `Mode` campo sia nella `RequestBody` definizione del task HTTP che nella EventBridge connessione. Step Functionsutilizza il valore del `Mode` campo specificato nella connessione.
+ Se si specifica il corpo della richiesta come stringa anziché come oggetto JSON e la EventBridge connessione contiene anche il corpo della richiesta, non è Step Functions possibile unire il corpo della richiesta specificato in entrambe queste posizioni. Fallisce l'operazione HTTP con l'`States.Runtime`errore.
Step Functionsapplica tutte le trasformazioni e serializza il corpo della richiesta dopo aver completato la fusione del corpo della richiesta.
L'esempio seguente imposta i `RequestBody` campi `Headers``QueryParameters`, e sia nel task HTTP che nella connessione. EventBridge
**Definizione del task HTTP**
```
{
"Comment": "Data merging example for HTTP Task and EventBridge connection",
"StartAt": "ListCustomers",
"States": {
"ListCustomers": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"Authentication": {
"ConnectionArn": "arn:aws:events:region:account-id:connection/Example/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"ApiEndpoint": "https:/example.com/path",
"Method": "GET",
"Headers": {
"Request-Id": "my_request_id",
"Header-Param": "state_machine_header_param"
},
"RequestBody": {
"Job": "Software Engineer",
"Company": "AnyCompany",
"BodyParam": "state_machine_body_param"
},
"QueryParameters": {
"QueryParam": "state_machine_query_param"
}
}
}
}
}
```
**connessione EventBridge**
```
{
"AuthorizationType": "API_KEY",
"AuthParameters": {
"ApiKeyAuthParameters": {
"ApiKeyName": "ApiKey",
"ApiKeyValue": "key_value"
},
"InvocationHttpParameters": {
"BodyParameters": [
{
"Key": "BodyParam",
"Value": "connection_body_param"
}
],
"HeaderParameters": [
{
"Key": "Header-Param",
"Value": "connection_header_param"
}
],
"QueryStringParameters": [
{
"Key": "QueryParam",
"Value": "connection_query_param"
}
]
}
}
}
```
In questo esempio, le chiavi duplicate vengono specificate nel task e nella EventBridge connessione HTTP. Pertanto, Step Functions sovrascrive i valori del task HTTP con i valori della connessione. Il seguente frammento di codice mostra la richiesta HTTP Step Functions inviata all'API HTTPS.
```
POST /path?QueryParam=connection_query_param HTTP/1.1
Apikey: key_value
Content-Length: 79
Content-Type: application/json; charset=UTF-8
Header-Param: connection_header_param
Host: example.com
Range: bytes=0-262144
Request-Id: my_request_id
User-Agent: Amazon|StepFunctions|HttpInvoke|region
{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}
```
## Applicazione della codifica URL nel corpo della richiesta
Per impostazione predefinita, Step Functions invia il corpo della richiesta come dati JSON a un endpoint API. Se il tuo provider di API HTTPS richiede corpi di `form-urlencoded` richiesta, devi specificare la codifica URL per i corpi della richiesta. Step Functionsquindi codifica automaticamente l'URL del corpo della richiesta in base all'opzione di codifica URL selezionata.
La codifica URL viene specificata utilizzando il campo. `Transform` Questo campo contiene il `RequestBodyEncoding` campo che specifica se si desidera applicare o meno la codifica URL per i corpi della richiesta. Quando specifichi il `RequestBodyEncoding` campo, Step Functions converte il corpo della richiesta JSON in quello della richiesta prima di chiamare l'`form-urlencoded`API HTTPS. È inoltre necessario specificare l'`content-type`intestazione in `application/x-www-form-urlencoded` quanto i dati con codifica URL APIs accettano l'intestazione. `content-type`
Per codificare gli array nel corpo della richiesta, Step Functions fornisce le seguenti opzioni di codifica dell'array.
+ `INDICES`— Ripete una chiave per ogni elemento di un array e aggiunge una parentesi, [], alla chiave per indicare che si tratta di un array. Questa parentesi contiene l'indice dell'elemento dell'array. L'aggiunta dell'indice consente di specificare l'ordine degli elementi dell'array. Per impostazione predefinita, Step Functions utilizza questa opzione di codifica.
Ad esempio, se il corpo della richiesta contiene il seguente array.
```
{"array": ["a","b","c","d"]}
```
Step Functionscodifica questo array nella seguente stringa.
```
array[0]=a&array[1]=b&array[2]=c&array[3]=d
```
+ `REPEAT`— Ripete una chiave per ogni elemento di un array.
Ad esempio, se il corpo della richiesta contiene il seguente array.
```
{"array": ["a","b","c","d"]}
```
Step Functionscodifica questo array nella seguente stringa.
```
array=a&array=b&array=c&array=d
```
+ `COMMAS`— Codifica tutti i valori di una chiave come elenco di valori delimitato da virgole.
Ad esempio, se il corpo della richiesta contiene il seguente array.
```
{"array": ["a","b","c","d"]}
```
Step Functionscodifica questo array nella seguente stringa.
```
array=a,b,c,d
```
+ `BRACKETS`— Ripete una chiave per ogni elemento di un array e aggiunge una parentesi, [], alla chiave per indicare che si tratta di una matrice.
Ad esempio, se il corpo della richiesta contiene il seguente array.
```
{"array": ["a","b","c","d"]}
```
Step Functionscodifica questo array nella seguente stringa.
```
array[]=a&array[]=b&array[]=c&array[]=d
```
## Autorizzazioni IAM per eseguire un task HTTP
Il ruolo di esecuzione della macchina a stati deve disporre delle seguenti autorizzazioni affinché un task HTTP possa chiamare un'API HTTPS:
+ `states:InvokeHTTPEndpoint`
+ `events:RetrieveConnectionCredentials`
+ `secretsmanager:GetSecretValue`
+ `secretsmanager:DescribeSecret`
Il seguente esempio di policy IAM concede i privilegi minimi richiesti al ruolo di macchina a stati per chiamare Stripe. APIs Questa policy IAM concede inoltre l'autorizzazione al ruolo della macchina a stati per accedere a una EventBridge connessione specifica, incluso il segreto per questa connessione archiviato in Secrets Manager.
****
```
{
"Version":"2012-10-17",
"Statement": [
{
"Sid": "Statement1",
"Effect": "Allow",
"Action": "states:InvokeHTTPEndpoint",
"Resource": "arn:aws:states:us-east-2:123456789012:stateMachine:myStateMachine",
"Condition": {
"StringEquals": {
"states:HTTPMethod": "GET"
},
"StringLike": {
"states:HTTPEndpoint": "https://api.stripe.com/*"
}
}
},
{
"Sid": "Statement2",
"Effect": "Allow",
"Action": [
"events:RetrieveConnectionCredentials"
],
"Resource": "arn:aws:events:us-east-2:123456789012:connection/oauth_connection/aeabd89e-d39c-4181-9486-9fe03e6f286a"
},
{
"Sid": "Statement3",
"Effect": "Allow",
"Action": [
"secretsmanager:GetSecretValue",
"secretsmanager:DescribeSecret"
],
"Resource": "arn:aws:secretsmanager:*:*:secret:events!connection/*"
}
]
}
```
## Esempio di attività HTTP
La seguente definizione di macchina a stati mostra un task HTTP che include i `RequestBody` parametri `Headers` `QueryParameters``Transform`,, e. L'HTTP Task richiama un'API Stripe, https://api.stripe.com/v1/ invoices, per generare una fattura. L'HTTP Task specifica anche la codifica URL per il corpo della richiesta utilizzando l'opzione di codifica. `INDICES`
Assicurati di aver creato una connessione. EventBridge L'esempio seguente mostra una connessione creata utilizzando il tipo di autenticazione BASIC.
```
{
"Type": "BASIC",
"AuthParameters": {
"BasicAuthParameters": {
"Password": "myPassword",
"Username": "myUsername"
},
}
}
```
Ricordati di sostituire il *italicized* testo con le informazioni specifiche della risorsa.
```
{
"Comment": "A state machine that uses HTTP Task",
"StartAt": "CreateInvoiceAPI",
"States": {
"CreateInvoiceAPI": {
"Type": "Task",
"Resource": "arn:aws:states:::http:invoke",
"Parameters": {
"ApiEndpoint": "https://api.stripe.com/v1/invoices",
"Method": "POST",
"Authentication": {
"ConnectionArn": ""arn:aws:events:region:account-id:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
},
"Headers": {
"Content-Type": "application/x-www-form-urlencoded"
},
"RequestBody": {
"customer.$": "$.customer_id",
"description": "Monthly subscription",
"metadata": {
"order_details": "monthly report data"
}
},
"Transform": {
"RequestBodyEncoding": "URL_ENCODED",
"RequestEncodingOptions": {
"ArrayFormat": "INDICES"
}
}
},
"Retry": [
{
"ErrorEquals": [
"States.Http.StatusCode.429",
"States.Http.StatusCode.503",
"States.Http.StatusCode.504",
"States.Http.StatusCode.502"
],
"BackoffRate": 2,
"IntervalSeconds": 1,
"MaxAttempts": 3,
"JitterStrategy": "FULL"
}
],
"Catch": [
{
"ErrorEquals": [
"States.Http.StatusCode.404",
"States.Http.StatusCode.400",
"States.Http.StatusCode.401",
"States.Http.StatusCode.409",
"States.Http.StatusCode.500"
],
"Comment": "Handle all non 200 ",
"Next": "HandleInvoiceFailure"
}
],
"End": true
}
}
}
```
Per eseguire questa macchina a stati, fornisci l'ID cliente come input, come mostrato nell'esempio seguente:
```
{
"customer_id": "1234567890"
}
```
L'esempio seguente mostra la richiesta HTTP Step Functions inviata all'API Stripe.
```
POST /v1/invoices HTTP/1.1
Authorization: Basic
Content-Type: application/x-www-form-urlencoded
Host: api.stripe.com
Range: bytes=0-262144
Transfer-Encoding: chunked
User-Agent: Amazon|StepFunctions|HttpInvoke|region
description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890
```
## Test di un task HTTP
Puoi utilizzare l'[TestState](https://docs.aws.amazon.com/step-functions/latest/apireference/API_TestState.html)API tramite la console, l'SDK o AWS CLI per [testare](test-state-isolation.md) un task HTTP. La procedura seguente descrive come utilizzare l' TestState API nella Step Functions console. Puoi testare in modo iterativo la richiesta, la risposta e i dettagli di autenticazione dell'API finché l'HTTP Task non funzioni come previsto.
**Verifica lo stato di un task HTTP nella console Step Functions**
1. Apri la [console Step Functions](https://console.aws.amazon.com/states/home?region=us-east-1#/).
1. Scegli **Crea macchina a stati** per iniziare a creare una macchina a stati o scegli una macchina a stati esistente che contiene un task HTTP.
Fai riferimento al Passaggio 4 se stai testando l'attività in una macchina a stati esistente.
1. In Workflow Studio, configura visivamente un'attività HTTP. [Modalità progettazione](workflow-studio.md#wfs-interface-design-mode) Oppure scegli la modalità Codice per copiare e incollare la definizione della macchina a stati dal tuo ambiente di sviluppo locale.
1. In modalità Progettazione, scegliete **Test state** nel [Pannello Inspector](workflow-studio.md#workflow-studio-components-formdefinition) pannello di Workflow Studio.
1. Nella finestra di dialogo **Test state**, effettuate le seguenti operazioni:
1. Per **Ruolo di esecuzione**, scegliete un ruolo di esecuzione per testare lo stato. Se non disponi di un ruolo con [autorizzazioni sufficienti](#connect-http-task-permissions) per un'attività HTTP, consulta [Ruolo per il test delle attività HTTP in Workflow Studio](manage-state-machine-permissions.md#test-state-role-http) per creare un ruolo.
1. (Facoltativo) Fornisci qualsiasi input JSON necessario allo stato selezionato per il test.
1. Per il **livello di ispezione**, mantieni la selezione predefinita di **INFO**. Questo livello mostra lo stato della chiamata API e lo stato dell'output. Questo è utile per verificare rapidamente la risposta dell'API.
1. Scegli **Avvia test**.
1. Se il test ha esito positivo, l'output dello stato viene visualizzato sul lato destro della finestra di dialogo **Test state**. Se il test fallisce, viene visualizzato un errore.
Nella scheda **Dettagli dello stato** della finestra di dialogo, puoi vedere la definizione dello stato e un link alla tua [EventBridgeconnessione](#http-task-authentication).
1. Modificate il **livello di ispezione** in **TRACE**. Questo livello mostra la richiesta e la risposta HTTP non elaborate ed è utile per verificare intestazioni, parametri di query e altri dettagli specifici dell'API.
1. **Scegli la casella di controllo Rivela segreti.** In combinazione con **TRACE**, questa impostazione consente di visualizzare i dati sensibili inseriti dalla EventBridge connessione, come le chiavi API. L'identità IAM utente che utilizzi per accedere alla console deve disporre dell'autorizzazione per eseguire l'`states:RevealSecrets`azione. Senza questa autorizzazione, all'avvio Step Functions del test viene generato un errore di accesso negato. Per un esempio di IAM policy che imposta l'`states:RevealSecrets`autorizzazione, vedi[IAMautorizzazioni per l'utilizzo dell'API TestState](test-state-isolation.md#test-state-permissions).
L'immagine seguente mostra un test per un task HTTP che ha esito positivo. Il **livello di ispezione** per questo stato è impostato su **TRACE**. La scheda **Richiesta e risposta HTTP** nell'immagine seguente mostra il risultato della chiamata all'API HTTPS.
![\[Output di uno stato selezionato che supera il test per il livello TRACE.\]](http://docs.aws.amazon.com/it_it/step-functions/latest/dg/images/test-state-trace-success.png)
1. Scegli **Avvia test**.
1. Se il test ha esito positivo, puoi visualizzare i dettagli HTTP nella scheda **Richiesta e risposta HTTP**.
## Risposte HTTP Task non supportate
Un task HTTP ha esito negativo e restituisce l'`States.Runtime`errore se una delle seguenti condizioni è vera per la risposta restituita:
+ La risposta contiene un'intestazione del tipo di contenuto di`application/octet-stream`,`image/*`, `video/*` o. `audio/*`
+ La risposta non può essere letta come una stringa valida. Ad esempio, dati binari o di immagine.
## Errori di connessione
Se si verifica EventBridge un problema durante la connessione all'API specificata durante l'esecuzione del flusso di lavoro, Step Functions genera l'errore nel flusso di lavoro. Gli errori di connessione hanno il prefisso. `Events.ConnectionResource.`
Questi errori includono:
+ `Events.ConnectionResource.InvalidConnectionState`
+ `Events.ConnectionResource.InvalidPrivateConnectionState`
+ `Events.ConnectionResource.AccessDenied`
+ `Events.ConnectionResource.ResourceNotFound`
+ `Events.ConnectionResource.AuthInProgress`
+ `Events.ConnectionResource.ConcurrentModification`
+ `Events.ConnectionResource.InternalError`