Chiama terze parti APIs nei flussi di lavoro Step Functions

Un HTTP Task è un tipo di Stato del flusso di lavoro delle attività stato che ti consente di chiamare qualsiasi terza parte pubblicaAPI, come Salesforce e Stripe, nei tuoi flussi di lavoro. Per chiamare una terza parteAPI, utilizza lo stato Task con la risorsa. arn:aws:states:::http:invoke Quindi, fornisci i dettagli di configurazione dell'APIendpoint, come il API URL metodo che desideri utilizzare e i dettagli di autenticazione.

Se utilizzi Workflow Studio per creare una macchina a stati che contiene un HTTP Task, Workflow Studio genera automaticamente un ruolo di esecuzione con IAM le politiche per il HTTP Task. Per ulteriori informazioni, consulta Ruolo per il test HTTP delle attività in Workflow Studio.

HTTPDefinizione dell'attività

La ASLdefinizione rappresenta un'HTTPattività con una http:invoke risorsa. La seguente definizione di HTTP Task richiama uno Stripe API che restituisce un elenco di tutti i clienti.

"Call third-party API": {
  "Type": "Task",
  "Resource": "arn:aws:states:::http:invoke",
  "Parameters": {
    "ApiEndpoint": "https://api.stripe.com/v1/customers",
    "Authentication": {
      "ConnectionArn": "arn:aws:events:us-east-2:123456789012:connection/Stripe/81210c42-8af1-456b-9c4a-6ff02fc664ac"
    },
    "Method": "GET"
  },
  "End": true
}

HTTPCampi delle attività

Un'HTTPattività include i seguenti campi nella sua definizione.

Autenticazione per un task HTTP

Un HTTP Task richiede una EventBridge connessione, che gestisce in modo sicuro le credenziali di autenticazione di un API provider. Una connessione specifica il tipo di autorizzazione e le credenziali da utilizzare per autorizzare una terza parte. API L'utilizzo di una connessione consente di evitare l'inserimento di segreti codificati, come API le chiavi, nella definizione della macchina a stati. Una EventBridge connessione supporta gli schemi di autorizzazione Basic OAuth e API Key.

Quando si crea una EventBridge connessione, si forniscono i dettagli di autenticazione. È inoltre possibile includere i parametri header, body e query necessari per l'autorizzazione con unAPI. È necessario includere la connessione ARN in qualsiasi HTTP attività che richiami una terza parteAPI.

Quando si crea una connessione e si aggiungono parametri di autorizzazione, EventBridge crea un indirizzo segreto 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 utente autorizzato a utilizzare Secrets Manager. Per ulteriori informazioni sulle IAM autorizzazioni necessarie alla macchina a stati per accedere a una EventBridge connessione, vedereIAMautorizzazioni per eseguire un'attività HTTP.

L'immagine seguente mostra come Step Functions gestisce l'autenticazione per le API chiamate di terze parti utilizzando una EventBridge connessione. La EventBridge connessione che gestisce le credenziali di un API provider terzo. EventBridgecrea un indirizzo segreto Secrets Manager per memorizzare i parametri di connessione e autorizzazione in forma crittografata.

Unione dei dati di EventBridge connessione e HTTP di definizione delle attività

Quando richiami un HTTP Task, puoi specificare i dati nella tua EventBridge connessione e nella definizione del HTTP Task. Questi dati includono HeadersQueryParameters, e RequestBody parametri. Prima di chiamare una terza parteAPI, 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 HTTP Task ha esito negativo e viene restituito l'States.Runtimeerrore.

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

L'elenco seguente descrive come Step Functions unire i dati prima di chiamare una terza parte: API

L'esempio seguente imposta i RequestBody campi HeadersQueryParameters, e sia nel Task che nella connessione. HTTP EventBridge

HTTPDefinizione dell'attività

{
  "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:us-east-1:123456789012: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 in HTTP Attività e EventBridge connessione. Pertanto, Step Functions sovrascrive i valori del HTTP Task con i valori della connessione. Il seguente frammento di codice mostra la HTTP richiesta Step Functions inviata alla terza parte. API

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|us-east-1

{"Job":"Software Engineer","Company":"AnyCompany","BodyParam":"connection_body_param"}

Applicazione della URL codifica -encoding sul corpo della richiesta

Per impostazione predefinita, Step Functions invia il corpo della richiesta come JSON dati a un API endpoint. Se il API provider di terze parti richiede i corpi delle form-urlencoded richieste, è necessario specificare URL -encoding per i corpi della richiesta. Step Functionsquindi URL -codifica automaticamente il corpo della richiesta in base all'opzione URL -encoding selezionata.

Specificate URL -encoding usando il campo. Transform Questo campo contiene il RequestBodyEncoding campo che specifica se si desidera applicare o meno URL -encoding ai corpi della richiesta. Quando specificate il RequestBodyEncoding campo, Step Functions converte il corpo della richiesta in quello della JSON richiesta prima di chiamare la form-urlencoded terza parte. API È inoltre necessario specificare l'content-typeintestazione in application/x-www-form-urlencoded quanto APIs i dati con URL codifica accettata prevedono l'intestazione. content-type

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

IAMautorizzazioni per eseguire un'attività HTTP

Il ruolo di esecuzione della macchina a stati deve avere lestates:InvokeHTTPEndpoint, events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue, e secretsmanager:DescribeSecret le autorizzazioni affinché un HTTP Task possa chiamare una terza parte. API Il seguente esempio di IAM politica concede i privilegi minimi richiesti al ruolo di macchina a stati per chiamare Stripe. APIs Questa IAM politica 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/*"
        }
    ]
}

HTTPEsempio di attività

La seguente definizione di macchina a stati mostra un HTTP Task che include i RequestBody parametri Headers QueryParametersTransform,, e. Il HTTP Task chiama StripeAPI, https://api.stripe.com/v1/ fattura, per generare una fattura. Il HTTP Task specifica anche URL -encoding 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 BASIC autenticazione.

{
    "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:us-east-2:123456789012: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 HTTP richiesta che Step Functions viene inviata a StripeAPI.

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|us-east-1

description=Monthly%20subscription&metadata%5Border_details%5D=monthly%20report%20data&customer=1234567890

Test di un'attività HTTP

Puoi utilizzarlo TestStateAPItramite la console o AWS CLI per testare un HTTP Task. SDK La procedura seguente descrive come utilizzare il TestState API nella Step Functions console. Puoi testare in modo iterativo i dettagli della API richiesta, della risposta e dell'autenticazione finché il HTTP Task non funzioni come previsto.

Risposte alle attività non supportate HTTP

Un HTTP task ha esito negativo con l'States.Runtimeerrore se una delle seguenti condizioni è vera per la risposta restituita: