Notas importantes do Amazon API Gateway - Amazon API Gateway

As traduções são geradas por tradução automática. Em caso de conflito entre o conteúdo da tradução e da versão original em inglês, a versão em inglês prevalecerá.

Notas importantes do Amazon API Gateway

Notas importantes do Amazon API Gateway para APIs REST e WebSocket

  • O API Gateway não é compatível com o compartilhamento de um nome de domínio personalizado em APIs REST e WebSocket.

  • Nomes de estágio podem conter apenas caracteres alfanuméricos, hífens e sublinhados. O tamanho máximo é de 128 caracteres.

  • Os caminhos /ping e /sping são reservados para a verificação de integridade do serviço. O uso desses recursos em nível raiz da API com domínios personalizados não conseguirá produzir o resultado esperado.

  • No momento, o API Gateway limita os eventos de log a 1.024 bytes. Eventos de log maiores do que 1024 bytes, como corpos de solicitação e resposta, serão truncados pelo API Gateway antes do envio para o CloudWatch Logs.

  • Atualmente, as métricas do CloudWatch limitam os nomes e valores de dimensão a 255 caracteres XML válidos. (Para obter mais informações, consulte o Guia do usuário do CloudWatch.) Os valores de dimensão são uma função de nomes definidos pelo usuário, incluindo o nome da API, o nome do rótulo (estágio) e o nome do recurso. Ao escolher esses nomes, tenha cuidado para não exceder os limites de métricas do CloudWatch.

  • O tamanho máximo de um modelo de mapeamento é de 300 KB.

Notas importantes do Amazon API Gateway para APIs WebSocket

  • O API Gateway é compatível com cargas de mensagem de até 128 KB com quadros no tamanho máximo de 32 KB. Se uma mensagem exceder 32 KB, é necessário dividi-la em vários quadros, cada qual contendo 32 KB ou menos. Se uma mensagem maior for recebida, a conexão será encerrada com o código 1009.

Notas importantes do Amazon API Gateway para APIs REST

  • O caractere pipe de texto simples (|) não tem suporte para nenhuma solicitação de sequência de consulta de URL e deve ser codificado pela URL.

  • O caractere ponto-e-vírgula (;) não tem suporte para nenhuma string de consulta de URL da solicitação e resulta nos dados divididos. Em geral, as APIs REST decodificam parâmetros de solicitação codificados em URL antes de passá-los para integrações de back-end.

  • Ao usar o console do API Gateway para testar uma API, você pode obter a resposta “unknown endpoint errors” (erros de endpoint desconhecido) se um certificado autoassinado for apresentado ao backend, o certificado intermediário estiver ausente da cadeia de certificados ou qualquer outra exceção relacionada a certificados irreconhecíveis for lançada pelo backend.

  • Para uma entidade Resource ou Method da API com integração privada, é necessário excluí-la depois de remover as referências codificadas permanentemente de um VpcLink. Caso contrário, sua integração será suspensa e você receberá uma mensagem de erro informando que o link da VPC ainda está em uso, mesmo se a entidade Resource ou Method tiver sido excluída. Esse comportamento não se aplica quando a integração privada faz referência ao VpcLink por meio de uma variável de estágio.

  • Os backends a seguir podem não ser compatíveis com a autenticação de cliente SSL de uma forma que seja compatível com o API Gateway:

  • O API Gateway é compatível com a maior parte da especificação do OpenAPI 2.0 e da especificação do OpenAPI 3.0, com as seguintes exceções:

    • Segmentos de caminho só podem conter caracteres alfanuméricos, sublinhados, hifens, pontos, vírgulas, dois-pontos e chaves. Parâmetros de caminho devem ser segmentos de caminho separados. Por exemplo, "resource/{path_parameter_name}" é válido; "resource{path_parameter_name}" não é.

    • Nomes de modelo podem conter apenas caracteres alfanuméricos.

    • Para parâmetros de entrada, somente os atributos a seguir são compatíveis: name, in, required, type, description. Outros atributos são ignorados.

    • Se usado, o tipo securitySchemes deverá ser apiKey. No entanto, OAuth 2 e autenticação básica HTTP são compatíveis por meio de autorizadores do Lambda; a configuração do OpenAPI é obtida por meio de extensões do fornecedor.

    • O campo deprecated não tem suporte e é descartado em APIs exportadas.

    • Os modelos do API Gateway são definidos usando esquema JSON rascunho 4 em vez do esquema JSON usado pelo OpenAPI.

    • O parâmetro discriminator não tem suporte em nenhum objeto de esquema.

    • Não há suporte para a tag example.

    • exclusiveMinimum não é compatível com o API Gateway.

    • As marcas maxItems e minItems não estão incluídas na validação de solicitação simples. Para resolver esse problema, atualize o modelo após a importação, antes de fazer a validação.

    • oneOf não é compatível com OpenAPI 2.0 ou a geração de SDK.

    • Não há suporte para o campo readOnly.

    • $ref não pode ser usado para referenciar outros arquivos.

    • Definições de resposta do formulário "500": {"$ref": "#/responses/UnexpectedError"} não têm suporte na raiz do documento do OpenAPI. Para contornar esse problema, substitua a referência pelo esquema embutido.

    • Não há suporte para números do tipo Int32 ou Int64. Um exemplo é mostrado conforme a seguir:

      "elementId": { "description": "Working Element Id", "format": "int32", "type": "number" }
    • O tipo de formato de número decimal ("format": "decimal") não tem suporte em uma definição de esquema.

    • Em respostas de método, a definição de esquema deve ser de um tipo de objeto e não pode ser de tipos primitivos. Por exemplo, não há suporte para "schema": { "type": "string"}. No entanto, você pode contornar esse problema usando o seguinte tipo de objeto:

      "schema": { "$ref": "#/definitions/StringResponse" } "definitions": { "StringResponse": { "type": "string" } }
    • O API Gateway não usa segurança no nível raiz definida na especificação do OpenAPI. Portanto, é necessário definir a segurança em um nível de operação a ser adequadamente aplicado.

    • A palavra-chave default não é compatível.

  • O API Gateway impõe as seguintes restrições e limitações ao lidar com métodos com a integração do Lambda ou a integração HTTP.

    • Os nomes de cabeçalho e parâmetros de consulta são processados em uma forma com distinção entre letras maiúsculas e minúsculas.

    • A tabela a seguir lista os cabeçalhos que podem ser descartados, remapeados ou modificados quando enviados ao seu endpoint de integração ou enviados de volta pelo seu endpoint de integração. Nesta tabela:

      • Remapped significa que o nome de cabeçalho é alterado de <string> para X-Amzn-Remapped-<string>.

        Remapped Overwritten significa que o nome de cabeçalho é alterado de <string> para X-Amzn-Remapped-<string> e o valor é substituído.

      Nome do cabeçalho Solicitação (http/http_proxy/lambda) Resposta (http/http_proxy/lambda)
      Age Passagem Passagem
      Accept Passagem Descartado/Passagem/Passagem
      Accept-Charset Passagem Passagem
      Accept-Encoding Passagem Passagem
      Authorization Passagem * Remapeado
      Connection Descartado/Passagem/Descartado Remapeado
      Content-Encoding Passagem/Descartado/Passagem Passagem
      Content-Length Passagem (gerada com base no corpo) Passagem
      Content-MD5 Descartado Remapeado
      Content-Type Passagem Passagem
      Date Passagem Remapeado substituído
      Expect Descartado Descartado
      Host Substituído no endpoint de integração Descartado
      Max-Forwards Descartado Remapeado
      Pragma Passagem Passagem
      Proxy-Authenticate Descartado Descartado
      Range Passagem Passagem
      Referer Passagem Passagem
      Server Descartado Remapeado substituído
      TE Descartado Descartado
      Transfer-Encoding Descartado/Descartado/Exceção Descartado
      Trailer Descartado Descartado
      Upgrade Descartado Descartado
      User-Agent Passagem Remapeado
      Via Descartado/Descartado/Passagem Passagem/Descartado/Descartado
      Warn Passagem Passagem
      WWW-Authenticate Descartado Remapeado

      * O cabeçalho Authorization será descartado se contiver uma assinatura do Signature versão 4 ou se a autorização AWS_IAM for usada.

  • O SDK do Android de uma API gerada pelo API Gateway usa a classe java.net.HttpURLConnection. Essa classe lançará uma exceção sem tratamento, em dispositivos executando o Android 4.4 e anteriores, para uma resposta 401 resultante do remapeamento do cabeçalho WWW-Authenticate para X-Amzn-Remapped-WWW-Authenticate.

  • Diferentemente dos SDKs Java, Android e iOS gerados pelo API Gateway de uma API, o SDK JavaScript de uma API gerada pelo API Gateway não é compatível com a novas tentativas para erros de nível 500.

  • A invocação de teste de um método usa o tipo de conteúdo padrão de application/json e ignora especificações de todos os outros tipos de conteúdo.

  • Ao enviar solicitações para uma API transmitindo o cabeçalho X-HTTP-Method-Override, o API Gateway substituirá o método. Portanto, para transmitir o cabeçalho ao backend, o cabeçalho precisa ser adicionado à solicitação de integração.

  • Quando uma solicitação contém vários tipos de mídia em seu cabeçalho Accept, o API Gateway apenas respeita o primeiro tipo de mídia Accept. Na situação em que você não pode controlar a ordem dos tipos de mídia de Accept e o tipo de mídia do seu conteúdo binário não é o primeiro da lista, é possível adicionar o primeiro tipo de mídia Accept na lista binaryMediaTypes da sua API, e o API Gateway retornará seu conteúdo como binário. Por exemplo, para enviar um arquivo JPEG usando um elemento <img> em um navegador, o navegador pode enviar Accept:image/webp,image/*,*/*;q=0.8 em uma solicitação. Ao adicionar image/webp à lista, o endpoint binaryMediaTypes receberá o arquivo JPEG como binário.

  • A personalização da resposta de gateway padrão para 413 REQUEST_TOO_LARGE não é compatível no momento.

  • O API Gateway inclui um cabeçalho Content-Type para todas as respostas de integração. Por padrão, o tipo de conteúdo é application/json.