Suporte ao recurso API Gateway Formato de solicitação Autenticação e autorização Padrões de integração de serviço Formato de saída Tratamento de erros Políticas do IAM

Criar APIs REST do API Gateway com o Step Functions

Saiba como usar o Amazon API Gateway para criar, publicar, manter e monitorar APIs REST e HTTP com o Step Functions. Para fazer a integração com o API Gateway, você define um estado Task no Step Functions que chama diretamente um endpoint de HTTP do API Gateway ou de REST do API Gateway, sem escrever código ou depender de outra infraestrutura. Uma definição de estado Task inclui todas as informações necessárias para a chamada da API. Também é possível selecionar métodos de autorização diferentes.

Para saber mais sobre a integração com serviços da AWS no Step Functions, consulte Integração de produtos da e Transmitir parâmetros a uma API de serviço no Step Functions.

Principais recursos da integração otimizada do API Gateway

apigateway:invoke: não tem equivalente na integração de serviços do AWS SDK. Em vez disso, o serviço Optimized API Gateway chama o endpoint do API Gateway diretamente.

Suporte ao recurso API Gateway

A integração do API Gateway do Step Functions é compatível com alguns, mas não todos os recursos do API Gateway. Para obter uma lista mais detalhada dos recursos compatíveis, consulte o seguinte:

Compatível com as integrações da API REST do API Gateway e do API HTTP do API Gateway do Step Functions:
- Autorizadores: IAM (usando Singature Version 4), No Auth, Lambda Authorizers (baseados em parâmetros de solicitação e baseados em tokens com cabeçalho personalizado)
- Tipos de API: regional
- Gerenciamento de API: nomes de domínio de API do API Gateway, estágio da API, caminho, parâmetros de consulta, corpo da solicitação
Compatível com a integração da API HTTP do API Gateway do Step Functions. A integração da API REST do API Gateway do Step Functions, que fornece a opção de APIs otimizadas para o Edge, não é compatível.
Não compatível com a integração do API Gateway do Step Functions:
- Autorizadores: Amazon Cognito, Native Open ID Connect/OAuth 2.0, cabeçalho de autorização para autorizadores Lambda baseados em tokens
- Tipos de API: privado
- Gerenciamento de API: nomes de domínio personalizados

Para obter mais informações sobre API Gateway e as APIs HTTP e REST, consulte o seguinte:

A página Conceitos do Amazon API Gateway.
Como escolher entre APIs HTTP e REST no Guia do desenvolvedor do API Gateway.

Formato de solicitação

Quando você cria a definição de estado Task, o Step Functions valida os parâmetros, cria a URL necessária para realizar a chamada e, em seguida, chama a API. A resposta inclui o código de status HTTP, cabeçalhos e corpo da resposta. O formato da solicitação tem parâmetros obrigatórios e opcionais.

Parâmetros de solicitação obrigatórios

ApiEndpoint
- Tipo:: String
- O nome do host de um URL do API Gateway. O formato é <API ID>.execute-api.region.amazonaws.com.
  
  O ID da API só pode conter uma combinação dos seguintes caracteres alfanuméricos: 0123456789abcdefghijklmnopqrstuvwxyz
Method
- Tipo:: Enum
- O método HTTP, que deve ser um dos seguintes:
  - GET
  - POST
  - PUT
  - DELETE
  - PATCH
  - HEAD
  - OPTIONS

Parâmetros de solicitação opcionais

Headers
- Tipo:: JSON
- Os cabeçalhos HTTP permitem uma lista de valores associados à mesma chave.
Stage
- Tipo:: String
- O nome do estágio em que a API é implantada no API Gateway. É opcional para qualquer API HTTP que use o estágio $default.
Path
- Tipo:: String
- Parâmetros de caminho que são anexados após o endpoint da API.
QueryParameters
- Tipo:: JSON
- As strings de consulta só permitem uma lista de valores associados à mesma chave.
RequestBody
- Tipo: JSON ou String
- O corpo da solicitação HTTP. O tipo pode ser um objeto JSON ou String. RequestBody só é compatível com os métodos de HTTP PATCH, POST e PUT.
AllowNullValues
- Tipo: BOOLEAN: valor padrão: false
- Com a configuração padrão, os valores nulos no estado de entrada da solicitação não serão enviados à API. No exemplo a seguir, o campo category não será incluído na solicitação, a menos que AllowNullValues esteja definido como true na definição da máquina de estado.
```
{
    "NewPet": {
        "type": "turtle",
        "price": 123,
        "category": null
    }
}
```
  nota
  Por padrão, campos com valores nulos no estado de entrada da solicitação não serão enviados à API. É possível forçar o envio de valores nulos à API configurando AllowNullValues como true na definição da máquina de estado.
AuthType
- Tipo:: JSON
- O método de autenticação. O método padrão é NO_AUTH. Os valores permitidos são:
  - NO_AUTH
  - IAM_ROLE
  - RESOURCE_POLICY
  Consulte Autenticação e autorização para obter mais informações.

nota

Por questões de segurança, as seguintes chaves de cabeçalho HTTP não são permitidas atualmente:

Qualquer coisa prefixada com X-Forwarded, X-Amz ou X-Amzn.
Authorization
Connection
Content-md5
Expect
Host
Max-Forwards
Proxy-Authenticate
Server
TE
Transfer-Encoding
Trailer
Upgrade
Via
Www-Authenticate

O exemplo de código a seguir mostra como invocar o API Gateway usando o 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"
    } 
}

Autenticação e autorização

Você pode usar os seguintes métodos de autenticação:

Sem autorização: chame a API diretamente sem nenhum método de autorização.
Perfil do IAM: com esse método, o Step Functions assume o papel da máquina de estado, assina a solicitação com Signature Version 4 (SigV4) e chama a API.
Política de recursos: o Step Functions autentica a solicitação e, em seguida, chama a API. Você deve anexar uma política de recursos à API que especifique o seguinte:
1. A máquina de estado que invocará o API Gateway.
  
  Importante
  Você deve especificar a máquina de estado para limitar o acesso a ela. Caso contrário, qualquer máquina de estado que autentique a solicitação do API Gateway com a autenticação Política de recursos na API receberá acesso.
2. Esse Step Functions é o serviço que chama o API Gateway: "Service": "states.amazonaws.com".
3. O recurso que você deseja acessar, incluindo:
  - A região.
  - O ID da conta na região especificada.
  - O ID da API.
  - O nome do estágio.
  - O HTTP-VERB (método).
  - O especificador do caminho do recurso.
Para ver um exemplo de política de recursos, consulte Políticas do IAM para Step Functions e API Gateway.

Para obter mais informações sobre o formato do recurso, consulte Formato do recurso de permissões para executar a API no API Gateway no Guia do desenvolvedor do API Gateway.

nota
As políticas de recursos são compatíveis somente com a API REST.

Padrões de integração de serviço

A integração do API Gateway oferece suporte a dois padrões de integração de serviços:

Resposta de solicitação, que é o padrão de integração padrão. Ele permite que o Step Functions avance para a próxima etapa imediatamente após receber uma resposta HTTP.

Aguardar um retorno de chamada com um token de tarefa (.waitForTaskToken), que espera até que um token de tarefa seja retornado com uma carga útil. Para usar o .waitForTaskToken padrão, anexe .waitForTaskToken ao final do campo Recurso da definição da tarefa, conforme mostrado no seguinte exemplo:


{
    "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 de saída

Os seguintes parâmetros de saída são fornecidos:

Name	Tipo	Description
`ResponseBody`	`JSON` ou `String`	O corpo da resposta da chamada de API.
`Headers`	`JSON`	Os cabeçalhos de resposta.
`StatusCode`	`Integer`	O código de status HTTP da resposta.
`StatusText`	`String`	O texto do status da resposta.

Um exemplo de resposta:


{
    "ResponseBody": {
        "myBills": []
    },
    "Headers": { 
        "key": ["value1", "value2"]
    }, 
    "StatusCode": 200,
    "StatusText": "OK" 
}

Tratamento de erros

Quando ocorre um erro, error e cause são retornados da seguinte forma:

Se o código de status HTTP estiver disponível, o erro será retornado no formato ApiGateway.<HTTP Status Code>.
Se o código de status HTTP estiver indisponível, o erro será retornado no formato ApiGateway.<Exception>.

Em ambos os casos, cause é retornado como uma string.

O seguinte exemplo mostra uma resposta em que ocorreu um erro:


{
    "error": "ApiGateway.403", 
    "cause": "{\"message\":\"Missing Authentication Token\"}"
}

nota

Um código de status 2XX indica sucesso e nenhum erro será retornado. Todos os outros códigos de status ou exceções lançadas resultarão em um erro.

Políticas do IAM para chamadas para o Amazon API Gateway

Os modelos de exemplo a seguir mostram como o AWS Step Functions gera políticas do IAM com base nos recursos da definição da máquina de estado. Para obter mais informações, consulte Como o Step Functions gera políticas do IAM para serviços integrados e Descobrir padrões de integração de serviços no Step Functions.

Recursos:


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

O exemplo de código a seguir mostra uma política de recursos para chamar o 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": [
                        "<SourceStateMachineArn>"
                    ]
                }
            }
        }
    ]
}

Atenção O Javascript está desativado ou não está disponível no seu navegador.

Para usar a documentação da AWS, o Javascript deve estar ativado. Consulte as páginas de Ajuda do navegador para obter instruções.

Convenções do documento

Integrar serviços otimizados

Amazon Athena

Criar APIs REST do API Gateway com o Step Functions

Principais recursos da integração otimizada do API Gateway

Suporte ao recurso API Gateway

Formato de solicitação

Parâmetros de solicitação obrigatórios

Parâmetros de solicitação opcionais

nota

nota

Autenticação e autorização

Importante

nota

Padrões de integração de serviço

Formato de saída

Tratamento de erros

nota

Políticas do IAM para chamadas para o Amazon API Gateway