Chame terceiros APIs nos fluxos de trabalho do Step Functions

Uma HTTP tarefa é um tipo de Estado do fluxo de trabalho da tarefa estado que permite chamar qualquer pessoa pública ou terceirizadaAPI, como Salesforce e Stripe, em seus fluxos de trabalho. Para chamar um terceiroAPI, use o estado Tarefa com o arn:aws:states:::http:invoke recurso. Em seguida, forneça os detalhes da configuração do API endpoint, como o API URL método que você deseja usar e os detalhes da autenticação.

Se você usa o Workflow Studio para criar sua máquina de estado que contém uma HTTP tarefa, o Workflow Studio gera automaticamente uma função de execução com IAM políticas para a HTTP tarefa. Para obter mais informações, consulte Função para testar HTTP tarefas no Workflow Studio.

HTTPDefinição de tarefa

A ASLdefinição representa uma HTTP tarefa com http:invoke recurso. A definição de HTTP tarefa a seguir invoca um Stripe API que retorna uma lista de todos os clientes.

"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
}

HTTPCampos de tarefas

Uma HTTP tarefa inclui os seguintes campos em sua definição.

Autenticação para uma HTTP tarefa

Uma HTTP tarefa requer uma EventBridge conexão, que gerencia com segurança as credenciais de autenticação de um provedor. API Uma conexão especifica o tipo de autorização e as credenciais a serem usadas para autorizar um terceiro. API Usar uma conexão ajuda a evitar a codificação de segredos, como API chaves, na definição de sua máquina de estado. Uma EventBridge conexão suporta os esquemas de autorização BásicoOAuth,, e API Chave.

Ao criar uma EventBridge conexão, você fornece seus detalhes de autenticação. Você também pode incluir o cabeçalho, o corpo e os parâmetros de consulta necessários para autorização com umAPI. Você deve incluir a conexão ARN em qualquer HTTP tarefa que chame um terceiroAPI.

Quando você cria uma conexão e adiciona parâmetros de autorização, EventBridge cria uma entrada secreta AWS Secrets Manager. Nesse segredo, EventBridge armazena os parâmetros de conexão e autorização em um formato criptografado. Para criar ou atualizar uma conexão com sucesso, você deve usar uma Conta da AWS que tenha permissão para usar o Secrets Manager. Para obter mais informações sobre as IAM permissões que sua máquina de estado precisa para acessar uma EventBridge conexão, consulteIAMpermissões para executar uma HTTP tarefa.

A imagem a seguir mostra como Step Functions manipula a autenticação de API chamadas de terceiros usando uma EventBridge conexão. A EventBridge conexão que gerencia as credenciais de um API provedor terceirizado. EventBridgecria um segredo Secrets Manager para armazenar os parâmetros de conexão e autorização em um formato criptografado.

Mesclando dados de EventBridge conexão e definição de HTTP tarefas

Ao invocar uma HTTP Tarefa, você pode especificar dados em sua EventBridge conexão e sua definição de HTTP Tarefa. Esses dados incluem os parâmetros Headers, QueryParameters e RequestBody. Antes de chamar um terceiroAPI, o Step Functions mescla o corpo da solicitação com os parâmetros do corpo da conexão em todos os casos, exceto se o corpo da solicitação for uma string e os parâmetros do corpo da conexão não estiverem vazios. Nesse caso, a HTTP tarefa falha com o States.Runtime erro.

Se houver alguma chave duplicada especificada na definição da HTTP Tarefa e na EventBridge conexão, Step Functions substituirá os valores na HTTP Tarefa pelos valores na conexão.

A lista a seguir descreve como Step Functions mesclar dados antes de chamar um terceiroAPI:

O exemplo a seguir define os RequestBody campos HeadersQueryParameters, e na HTTP Tarefa e na EventBridge conexão.

HTTPDefinição de tarefa

{
  "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"
        }
      }
    }
  }
}

Conexão com o 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"
        }
      ]
    }
  }
}

Neste exemplo, chaves duplicadas são especificadas em HTTP Tarefa e EventBridge conexão. Portanto, Step Functions substitui os valores na HTTP Tarefa pelos valores na conexão. O trecho de código a seguir mostra a HTTP solicitação que é Step Functions enviada ao terceiro. 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"}

Aplicando a URL codificação -no corpo da solicitação

Por padrão, Step Functions envia o corpo da solicitação como JSON dados para um API endpoint. Se seu API provedor terceirizado exigir corpos de form-urlencoded solicitação, você deverá especificar URL -encoding para os corpos de solicitação. Step Functionsem seguida, URL codifica automaticamente o corpo da solicitação com base na opção URL -encoding selecionada.

Você especifica URL -encoding usando o Transform campo. Esse campo contém o RequestBodyEncoding campo que especifica se você deseja ou não aplicar URL -encoding aos corpos da solicitação. Quando você especifica o RequestBodyEncoding campo, Step Functions converte o corpo da JSON solicitação em corpo da form-urlencoded solicitação antes de chamar o terceiroAPI. Você também deve especificar o content-type cabeçalho application/x-www-form-urlencoded porque APIs os dados URL codificados em aceitação esperam o content-type cabeçalho.

Para codificar matrizes no corpo da solicitação, o Step Functions oferece as opções de codificação de matriz a seguir.

IAMpermissões para executar uma HTTP tarefa

Sua função de execução da máquina de estado deve ter as secretsmanager:DescribeSecret permissões states:InvokeHTTPEndpoint events:RetrieveConnectionCredentialssecretsmanager:GetSecretValue,, e para que uma HTTP tarefa chame um terceiroAPI. O exemplo IAM de política a seguir concede os privilégios mínimos necessários à sua função de máquina de estado para chamar o APIs Stripe. Essa IAM política também concede permissão à função de máquina de estado para acessar uma EventBridge conexão específica, incluindo o segredo dessa conexão que está armazenado no 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/*"
        }
    ]
}

HTTPExemplo de tarefa

A definição de máquina de estado a seguir mostra uma HTTP tarefa que inclui os RequestBody parâmetros Headers QueryParametersTransform,, e. A HTTP tarefa chama um StripeAPI, https://api.stripe.com/v1/ faturas, para gerar uma fatura. A HTTP tarefa também especifica a URL codificação -para o corpo da solicitação usando a opção de codificação. INDICES

Verifique se você criou uma conexão com o EventBridge. O exemplo a seguir mostra uma conexão criada usando o tipo BASIC auth.

{
    "Type": "BASIC",
    "AuthParameters": { 
        "BasicAuthParameters": { 
            "Password": "myPassword",
            "Username": "myUsername"
         },
    }
}

Lembre-se de substituir o italicized texto com as informações específicas do seu recurso.

{
  "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
    }
  }
}

Para executar essa máquina de estado, forneça o ID do cliente como entrada, conforme mostrado no seguinte exemplo:

{
    "customer_id": "1234567890"
}

O exemplo a seguir mostra a HTTP solicitação que é Step Functions enviada para o 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

Testando uma HTTP tarefa

Você pode usar o TestStateAPIpor meio do console ou o AWS CLI para testar uma HTTP tarefa. SDK O procedimento a seguir descreve como usar o TestState API no Step Functions console. Você pode testar iterativamente os detalhes da API solicitação, da resposta e da autenticação até que sua HTTP tarefa esteja funcionando conforme o esperado.

Respostas de HTTP tarefas não suportadas

Uma HTTP tarefa falhará com o States.Runtime erro se uma das seguintes condições for verdadeira para a resposta retornada: