Chiama le API HTTPS nei flussi di lavoro di Step Functions

Un HTTP Task è un tipo di Stato del flusso di lavoro delle attività stato che puoi utilizzare per chiamare le API HTTPS 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 HTTPS-based applicazioni in un Amazon Virtual Private Cloud.

Per l'autorizzazione e la connettività di rete, un'attività HTTP richiede un EventBridge connessione.

Per chiamare un'API HTTPS, usa Attività stato con 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 connessione dettagli.

Se usi Workflow Studio per creare la macchina a stati che contiene un'attività HTTP, Workflow Studio genera automaticamente un ruolo di esecuzione con IAM politiche per l'HTTP Task. Per ulteriori informazioni, consulta Ruolo per testare le attività HTTP in Workflow Studio.

Connettività per un'attività HTTP

Un task HTTP richiede un EventBridge connessione, che gestisce in modo sicuro le credenziali di autenticazione di un provider di API. A 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 rete point-to-point 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. Un EventBridge la connessione supporta gli schemi di autorizzazione Basic, OAuth e API Key.

Quando si crea un EventBridge connessione, fornisci i tuoi dati di autorizzazione e connettività di rete. Puoi anche includere i parametri di intestazione, corpo e query necessari per l'autorizzazione con un'API. È necessario includere l'ARN di connessione in qualsiasi attività HTTP che richiama un'API HTTPS.

Quando si crea una connessione, EventBridge crea un segreto nel AWS Secrets Manager. 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 che dispone del permesso di utilizzare Secrets Manager. Per ulteriori informazioni su IAM autorizzazioni necessarie alla macchina a stato per accedere a EventBridge connessione, vedi Autorizzazioni IAM per eseguire un task HTTP.

L'immagine seguente mostra come Step Functions gestisce l'autorizzazione per le chiamate API HTTPS utilizzando un EventBridge connessione. La EventBridge la connessione gestisce le credenziali di un provider di API HTTPS. EventBridge crea un segreto nel Secrets Manager per memorizzare i parametri di connessione e autorizzazione in forma crittografata. Nel caso di API private, EventBridge memorizza anche le configurazioni di connettività di rete.

Definizione dell'attività HTTP

La Definizione ASL rappresenta un'attività 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.

Fusione EventBridge dati di connessione e definizione delle attività HTTP

Quando si richiama un Task HTTP, è possibile specificare i dati nel EventBridge connessione e definizione dell'attività 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 della connessione non sono vuoti. In questo caso, l'HTTP Task ha esito negativo con States.Runtime errore.

Se sono presenti chiavi duplicate specificate nella definizione dell'attività HTTP e nel EventBridge connessione, Step Functions sovrascrive i valori del Task HTTP con i valori della connessione.

L'elenco seguente descrive come Step Functions unisce i dati prima di chiamare un'API HTTPS:

L'esempio seguente imposta Headers, QueryParameters, e RequestBody campi sia nel Task HTTP che EventBridge connessione.

Definizione dell'attività 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 nell'attività HTTP e EventBridge connessione. Pertanto, Step Functions sovrascrive i valori del Task HTTP con i valori della connessione. Il seguente frammento di codice mostra la richiesta HTTP che Step Functions invia 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"}

Applicando URL-encoding ente su 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 form-urlencoded corpi delle richieste, è necessario specificare URL-encoding per gli organismi richiedenti. Step Functions quindi automaticamente URL-encodes il corpo della richiesta in base a URL-encoding opzione selezionata.

Tu specifichi URL-encoding utilizzando il Transform campo. Questo campo contiene RequestBodyEncoding campo che specifica se si desidera candidarsi o meno URL-encoding per gli enti preposti alla richiesta. Quando si specifica il RequestBodyEncoding campo, Step Functions converte il corpo della richiesta JSON in form-urlencoded corpo della richiesta prima di chiamare l'API HTTPS. È inoltre necessario specificare il content-type intestazione come application/x-www-form-urlencoded perché API che accettano URL-encoded i dati si aspettano il content-type intestazione.

Per codificare gli array nel corpo della richiesta, Step Functions fornisce le seguenti opzioni di codifica degli array.

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:

Il seguente esempio di policy IAM concede i privilegi minimi richiesti al tuo ruolo di macchina statale per chiamare le API di Stripe. Questa policy IAM concede inoltre l'autorizzazione al ruolo di macchina statale per accedere a uno specifico EventBridge connessione, incluso il segreto di questa connessione memorizzato in Secrets Manager.

Esempio di attività HTTP

La seguente definizione di macchina a stati mostra un Task HTTP che include Headers, QueryParameters, Transform, e RequestBody parametri. L'HTTP Task chiama un'API Stripe, https://api.stripe.com/v1/invoices, per generare una fattura. L'HTTP Task specifica inoltre URL-encoding per il corpo della richiesta utilizzando INDICES opzione di codifica.

Assicurati di aver creato un EventBridge connessione. 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 che Step Functions invia all'API Stripe.

POST /v1/invoices HTTP/1.1
Authorization: Basic <base64 of username and password>
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 usare il TestState API tramite la console, l'SDK o il AWS CLI a test un'attività HTTP. La procedura seguente descrive come utilizzare TestState API in Step Functions console. Puoi testare in modo iterativo i dettagli di richiesta, risposta e autenticazione dell'API finché l'HTTP Task non funziona come previsto.

Risposte alle attività HTTP non supportate

Un'operazione HTTP ha esito negativo con States.Runtime errore se una delle seguenti condizioni è vera per la risposta restituita:

Errori di connessione

Se EventBridge riscontra 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 sono preceduti da Events.ConnectionResource..

Questi errori includono: