API Gateway:Criar uma API

Etapa 1: Configurar uma API

Faça login no console do API Gateway. No painel de navegação à esquerda, escolha Manage APIs > APIs. Na página APIs, clique em Create API para criar e configurar uma nova API.

1. Configurar informações básicas

   Parameter	Description
   API Group	Unidade básica de gerenciamento de APIs. Crie um grupo de APIs antes de criar uma API. A seleção do grupo define automaticamente a região da API.
   API Name	Nome da API a ser criada. Cada nome de API dentro de um grupo deve ser único.
   Security Authentication	Atualmente, há suporte para Alibaba Cloud App e No Authentication. Alibaba Cloud App: permite que o chamador utilize um aplicativo autenticado para invocar a API. No Authentication: permite que qualquer usuário com conhecimento da definição de requisição da API inicie chamadas. O API Gateway encaminha a requisição diretamente ao serviço de back-end sem verificar a identidade do chamador. Recomendamos não definir Security Certification como No Authentication.
   Signature Algorithm	Algoritmo usado para assinar requisições de API. Valores válidos: HMAC_SHA256 HMAC_SHA1 e HMAC_SHA256: ao definir este valor, ambos os algoritmos serão aceitos.
   API Option	Recurso a ser habilitado na API. Valores válidos: Anti-replay Protection (X-Ca-Nonce Header Required) Forbid Internet Access Allow API Publish to Alibaba Cloud Marketplace Nota Se você selecionar Forbid Internet Access e precisar solicitar um nome de domínio VPC, clique em Apply for VPC domain name para acessar o console.
   Description	Descrição da API.

2. Configurar informações da requisição

   Na etapa Define API Request, configure as informações de requisição da API. As configurações incluem Protocol, Request Path, HTTP Method, Request Mode e Request Parameters.

   Parameter	Description
   Protocol	Protocolo de rede usado na requisição da API. Valores válidos: HTTP e HTTPS.
   Request Path	Caminho de requisição da API correspondente ao host do serviço. Esse caminho pode diferir do caminho real do serviço de back-end. Especifique um caminho válido e semanticamente preciso. É possível configurar parâmetros dinâmicos no caminho de requisição, o que exige a definição de parâmetros de caminho na requisição. Além disso, esses parâmetros podem ser mapeados para parâmetros de query e header recebidos pelo serviço de back-end.
   HTTP Method	Método padrão de requisição HTTP. Valores válidos: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS e ANY.
   Request Mode	Modo de transmissão dos parâmetros de requisição. Valores válidos: Request Parameter Map (Filter Out Unknown Parameters), Map (Pass-through Unknown Parameters) e Pass-through. Map (Filter Out Unknown Parameters): exige a configuração de mapeamentos de requisição e resposta para parâmetros de query, path e body form. O API Gateway transmite apenas os parâmetros configurados ao serviço de back-end e filtra os demais. Map (Pass-through Unknown Parameters): requer mapeamentos de requisição e resposta para parâmetros de query, path e body form. O API Gateway mapeia e valida somente os parâmetros configurados e repassa os desconhecidos ao serviço de back-end. Pass-through: dispensa a configuração de parâmetros de query e body form na requisição. No entanto, a configuração de parâmetros de caminho é obrigatória. O API Gateway repassa todos os parâmetros enviados pelo cliente diretamente ao serviço de back-end.

   Configurar parâmetros de requisição: Na seção Request Parameters, defina os parâmetros de requisição da API em locais específicos. Locais suportados: Parameter Path, Head e Query. Ao configurar um parâmetro de caminho dinâmico, forneça uma descrição para ele. Tipos de dados suportados: String, Int e Boolean.

   • Todos os nomes de parâmetros devem ser exclusivos.

   • Use as teclas de atalho na coluna No. para alterar a ordem dos parâmetros.

   • Para remover um parâmetro desnecessário, clique em Remove na coluna Actions.

   Nota

   Caso tenha configurado um parâmetro dinâmico no caminho de requisição, defina um parâmetro com o mesmo nome e configure Parameter Location como Parameter Path.

   Configurar regra de validação de parâmetro: Localize o parâmetro desejado e clique em Advanced Settings na coluna Actions. Na caixa de diálogo Advanced Settings, defina critérios como Maximum Length e Enumerated Value. O API Gateway pré-valida as requisições com base nessas regras e impede que requisições com parâmetros inválidos cheguem ao serviço de back-end. Isso reduz significativamente a carga de processamento no back-end.

3. Configurar serviço de back-end

   Na etapa Define Backend Service, estabeleça os mapeamentos de requisição e resposta para os parâmetros e especifique as configurações da API do serviço de back-end. Ao receber uma requisição, o API Gateway converte o formato dela para o formato exigido pelo serviço de back-end, conforme a configuração definida, e a encaminha.

   Configure basic information: Na seção Basic Settings for Backend Service, defina as informações básicas do serviço de back-end.

   Parameter	Description
   Configuration Mode	Define se você usará um serviço de back-end existente ou personalizará um novo. Valores válidos: Use Existing Backend Service Customize Backend Service
   Backend Service Type	Tipo do serviço de back-end. Valores válidos: HTTP/HTTPS Service, VPC, Function Compute, OSS e Mock. HTTP/HTTPS: opção selecionada por padrão. Indica que o API Gateway acessa o serviço de back-end via HTTP ou HTTPS. Selecione esta opção se houver comunicação direta entre o API Gateway e o back-end. Para usar um serviço HTTPS como back-end, configure um certificado SSL para ele. Function Compute: para utilizar o Function Compute como back-end, realize previamente as seguintes operações: crie uma função no console do Function Compute, especifique um nome de serviço e um nome de função e obtenha o ARN (Alibaba Cloud Resource Name) da função para o Function Compute. VPC: selecione esta opção se o serviço de back-end estiver implantado em uma Virtual Private Cloud (VPC). OSS: escolha esta opção caso o Object Storage Service (OSS) seja o serviço de back-end. Mock: indicado para simular resultados esperados do serviço de back-end HTTP ou HTTPS. Nota Não é possível criar serviços de back-end do tipo HTTP ou OSS em regiões fora da China ou na região China (Hong Kong).
   VPC Access Name	Se o serviço de back-end estiver implantado em uma VPC, especifique um nome de autorização de acesso à VPC.
   Backend Service URL	URL do host do serviço de back-end. O valor pode ser um nome de domínio ou seguir o formato http://host:port ou https://host:port. Deve começar obrigatoriamente com http:// ou https://.
   Backend Request Path	Caminho de requisição real da API no servidor de back-end. Para receber parâmetros dinâmicos no caminho do back-end, declare os mapeamentos de parâmetros especificando os locais e nomes dos parâmetros de requisição relevantes.
   HTTP Method	Método padrão de requisição HTTP. Valores válidos: PUT, GET, POST, DELETE, PATCH, HEAD, OPTIONS e ANY.
   Backend Service Timeout Period	Tempo permitido para o API Gateway enviar uma requisição recebida ao serviço de back-end e obter uma resposta. A contagem inicia no envio da requisição ao back-end e termina no recebimento da resposta. O tempo máximo é de 30s. Caso o API Gateway não receba uma resposta dentro desse prazo, ele interrompe o acesso ao back-end e retorna uma mensagem de erro.

   Configurar parâmetros do serviço de back-end: Na seção Backend Service Parameters, estabeleça os mapeamentos de requisição e resposta para os parâmetros. Há suporte para mapeamentos de nome e de localização. O API Gateway pode mapear um parâmetro de requisição de path, header, query ou body para um parâmetro de resposta em uma localização diferente. Assim, você encapsula seu serviço de back-end em uma API padronizada e profissional. Esta parte declara os mapeamentos entre parâmetros de requisição e resposta.

   Configure constant parameters: Na seção Constant Parameters, defina os parâmetros constantes. Esses parâmetros são invisíveis aos usuários. Ao receber requisições, o API Gateway adiciona os parâmetros constantes nos locais especificados e as encaminha ao serviço de back-end, atendendo às necessidades do seu negócio. Por exemplo, se quiser que o API Gateway anexe o parâmetro abc a cada requisição encaminhada ao back-end, configure-o como parâmetro constante. Dessa forma, o API Gateway insere automaticamente o parâmetro abc no local definido antes de enviar a requisição.

   Configurar parâmetros de sistema: Na seção System Parameters, configure os parâmetros de sistema suportados pelo API Gateway. Por padrão, o API Gateway não adiciona parâmetros de sistema às requisições de API. Para obtê-los, configure seus locais e nomes. A tabela a seguir lista os parâmetros de sistema disponíveis:

   Parameter	Description
   CaClientIp	Endereço IP do cliente que envia a requisição de API. Se você configurou o Web Application Firewall (WAF) ou a Content Delivery Network (CDN), o sistema registra o endereço IP de back-to-origin. O endereço IP real do cliente fica registrado em X-Forwarded-For.
   CaDomain	Nome de domínio usado para enviar a requisição de API.
   CaRequestHandleTime	Horário da requisição em UTC.
   CaRequestId	ID da requisição (RequestId).
   CaApiName	Nome da API.
   CaHttpSchema	Protocolo usado para chamar a API. Valores válidos: HTTP e HTTPS.
   CaProxy	Proxy usado para processar a requisição de API. Defina o valor como AliCloudApiGateway.
   CaClientUa	User agent do cliente que envia a requisição de API.
   CaCloudMarketInstanceId	ID da instância correspondente à commodity do Alibaba Cloud Marketplace adquirida pela primeira vez.
   CaAppId	ID do aplicativo usado para chamar a API.
   CaAppKey	Chave do aplicativo usado para chamar a API.
   CaAppExtendInfo	Extensões do aplicativo.
   CaStage	Ambiente onde a API é chamada. Valores válidos: RELEASE, TEST e PRE.
   CaInstanceId	ID da instância à qual a API pertence.
   CaSourceVpcId	VPC à qual o endereço IP do cliente pertence.

   Selecione Pass Host Header na seção Request Header Pass-through Settings da página de detalhes do grupo de APIs. Com essa opção ativada, o API Gateway repassa o parâmetro de header Host da requisição ao serviço de back-end. Se não selecionar Pass Host Header, o API Gateway envia o header Host especificado por você ao back-end. O código abaixo mostra um exemplo:

   Por exemplo, se você associar o nome de host xuemeng.XXXX.com a um grupo de APIs, o nome de host do serviço de back-end das APIs nesse grupo será apigatewayXXXXXXalicloudapi.com:8080. Os trechos de código a seguir mostram os diferentes nomes de host recebidos pelo serviço de back-end antes e depois da ativação do Pass Host Header.

   Com Pass Host Header habilitado, o seguinte nome de host é recebido:

Host: xuemeng.XXXX.com

Com Pass Host Header desabilitado, o seguinte nome de host é recebido:

Host: apigatewayXXXXXXalicloudapi.com:8080

1. Configurar informações de resposta

   Na etapa Define Response, configure Response ContentType, Response Example, Error Response Example e Error Codes.

Etapa 2: Depurar a API

Após criar e configurar a API, depure-a na página de depuração de API para garantir que funcione conforme o esperado.

Depois da criação e configuração, você será redirecionado para a página APIs. Nessa página, execute as operações abaixo para verificar se a API pode ser chamada e se a URL de requisição é válida:

1. Localize a API criada e clique no nome dela ou em Manage na coluna Actions para acessar a página Definition.

2. No painel de navegação à esquerda, clique em Debug API.

3. Na página exibida, especifique os parâmetros na seção Request Parameters e clique em Send Request.

O resultado aparecerá no lado direito da página.

Se uma resposta de sucesso for retornada, a API foi chamada corretamente.

Caso receba um código de status HTTP 4XX ou 5XX, ocorreu um erro durante a chamada da API. Para mais informações, consulte Como obter a mensagem de erro e Códigos de erro.

Etapa 3: Próximos passos

Após configurar e depurar a API, ela estará disponível para chamadas. Publique a API nos ambientes de teste, staging ou produção para depurações adicionais ou para uso dos clientes. Também é possível adicionar configurações de segurança à API, como anexar uma assinatura. Para mais detalhes, consulte Usar autenticação digest para chamar uma API.