Criação de uma API

Pré-requisitos

• Você criou um grupo de APIs. Se nenhum grupo de APIs estiver disponível, crie um fazendo referência a Criação de um grupo de APIs.
• Se o serviço de back-end precisar usar um canal de balanceamento de carga, crie um canal primeiro.
• Se você precisar usar um autorizador personalizado para autenticação de API, crie um.

Configurar configurações de front-end

1. Faça logon no console do APIG.
2. Selecione um gateway na parte superior do painel de navegação.

3. Escolha API Management > API Groups.
4. Clique em um nome de grupo.
5. Na página APIs, clique em Create.
   1. Configure os parâmetros de front-end descritos na tabela a seguir.

      Tabela 1 Definição de front-end

      Parâmetro	Descrição
      API Name	Digite um nome de API que esteja em conformidade com regras específicas para facilitar a pesquisa.
      Group	O grupo ao qual a API pertence.
      URL	Endereço de front-end, que consiste em um método, protocolo, nome de subdomínio e caminho. Method: selecione GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS ou ANY. ANY indica que todos os métodos de requisição são suportados. Protocol: selecione HTTP, HTTPS ou HTTP&HTTPS. O HTTPS é recomendado para a transmissão de dados importantes ou sensíveis. Subdomain Name: depuração do nome de domínio do grupo ao qual a API pertence. Path: caminho para solicitar a API. Inclua parâmetros em chaves. Por exemplo: /a/{b}. Ou use um sinal de mais (+) para corresponder aos parâmetros que começam com caracteres específicos. Por exemplo: /a/{b+}.
      Gateway Response	Exibido se uma solicitação de API não for processada. O APIG fornece um conjunto de respostas padrão e também permite que você crie novas respostas com códigos de status personalizados e conteúdo na página Group Information. O conteúdo da resposta deve estar no formato JSON.
      Matching	Opções: Exact match: a API pode ser chamada apenas usando o caminho de solicitação especificado. Prefix match: a API pode ser chamada usando caminhos começando com os caracteres correspondentes. Por exemplo, se você definir o caminho da solicitação como /test/AA e o modo de correspondência como Prefix match, a API poderá ser chamada usando /test/AA/CC, mas não poderá ser chamada usando /test/AACC. NOTA: Se você definir o modo de correspondência como Prefix match, os caracteres do caminho da solicitação da API excluindo o prefixo serão transmitidos de forma transparente para o back-end. Por exemplo, se você definir os caminhos de solicitação de front-end e back-end de uma API como /test/ e /test2/, respectivamente, e a API for chamada usando /test/AA/CC, os caracteres AA/CC serão transmitidos de forma transparente para o back-end. O URL de solicitação recebida pelo back-end é /test2/AA/CC/.
      Tags	Atributos usados para identificar rapidamente a API de outras APIs.
      Description	Descrição da API.

   2. Defina as configurações de segurança com base na tabela a seguir.

      Tabela 2 Configuração de segurança

      Parâmetro	Descrição
      Authentication Mode	Os seguintes modos de autenticação estão disponíveis: App: as solicitações para a API serão autenticadas pelo APIG. A autenticação da aplicação é recomendada. IAM: as solicitações para a API serão autenticadas pelo Identity and Access Management (IAM). Custom: as solicitações para a API serão autenticadas usando seu próprio sistema ou serviço de autenticação (por exemplo, um sistema de autenticação baseado em OAuth). None: nenhuma autenticação será necessária. A chamada da API varia dependendo do modo de autenticação. Para obter detalhes, consulte Guia de desenvolvedor. AVISO: Se você definir o modo de autenticação como IAM ou None, qualquer usuário do APIG poderá acessar a API, o que pode resultar em cobranças excessivas se a API for bombardeada com solicitações maliciosas. Se você definir o modo de autenticação como Custom, poderá criar uma função no FunctionGraph para interconectar com seu próprio sistema ou serviço de autenticação. Certifique-se de que o FunctionGraph esteja disponível na região atual.
      Simple Authentication	Esse parâmetro está disponível somente se você definir Security Authentication como App. Se você selecionar autenticação de aplicação, configure se deseja ativar a autenticação simples. Na autenticação simples, o parâmetro X-Apig-AppCode é adicionado ao cabeçalho da solicitação HTTP para uma resposta rápida. O APIG verifica apenas o AppCode e o conteúdo da solicitação não precisa ser assinado. A autenticação simples suporta apenas solicitações HTTPS e não suporta solicitações HTTP. Para mais detalhes, consulte Adição de um AppCode para autenticação simples. NOTA: Depois de ativar a autenticação simples para uma API existente, você precisa publicar a API novamente. Para mais detalhes, consulte Publicação de uma API.
      Two-Factor Authentication	Esse parâmetro estará disponível somente se o Authentication Mode estiver definido como App ou IAM. Determine se deve ativar a autenticação de dois fatores para a API. Se essa opção estiver ativada, as solicitações de API serão autenticadas usando um autorizador personalizado, além da autenticação da aplicação ou do IAM especificada.
      Custom Authorizer	Este parâmetro é obrigatório apenas se Authentication Mode estiver definido como Custom. Se nenhum autorizador personalizado estiver disponível, clique em Create Custom Authorizer para criar um.
      CORS	Determine se deve ativar o compartilhamento de recursos de origem cruzada (CORS). O CORS permite que navegadores enviem XMLHttpRequest para servidores em outros domínios, superando a limitação de que Asynchronous JavaScript and XML (AJAX) podem ser usados apenas no mesmo domínio. Existem dois tipos de solicitações CORS: Solicitações simples: solicitações que possuem o campo Origin no cabeçalho. Solicitações não tão simples: solicitações HTTP enviadas antes da solicitação real. Se o CORS (solicitação não tão simple) estiver ativado para uma API, outra API que use o método OPTIONS deve ser criada. Para obter detalhes, consulte Ativar CORS.

   3. (Opcional) Defina os parâmetros de solicitação descritos na tabela a seguir.

      Tabela 3 Configuração de parâmetros de solicitação

      Parâmetro	Descrição
      Parameter Name	Nome do parâmetro de solicitação. O nome de um parâmetro de caminho será exibido automaticamente nesta coluna. NOTA: O nome do parâmetro não diferencia maiúsculas de minúsculas. Não pode começar com x-apig- ou x-sdk-. O nome do parâmetro não pode ser x-stage. Se você definir a localização do parâmetro como HEADER, verifique se o nome do parâmetro não é Authorization ou X-Auth-Token e não contém sublinhados (_).
      Parameter Type	Opções: STRING e NUMBER. NOTA: Defina o tipo de parâmetros Boolean como STRING.
      Required	Determine se o parâmetro é necessário em cada solicitação enviada para chamar a API. Se você selecionar Yes, as solicitações de API que não contiverem o parâmetro serão rejeitadas.
      Passthrough	Determine se o parâmetro deve ser transmitido de forma transparente para o serviço de back-end.
      Enumerated Value	Valor enumerado do parâmetro. Use vírgulas (,) para separar vários valores enumerados. O valor deste parâmetro só pode ser um dos valores enumerados.
      Default Value	O valor que será usado se nenhum valor for especificado para o parâmetro quando a API for chamada. Se o parâmetro não for especificado em uma solicitação, o APIG enviará automaticamente o valor padrão para o serviço de back-end.
      Value Restrictions	Comprimento máximo/valor máximo: se Parameter Type estiver definido como STRING, defina o comprimento máximo do valor do parâmetro. Se Parameter Type estiver definido como NUMBER, defina o valor máximo do parâmetro. Comprimento mínimo/valor mínimo: se Parameter Type estiver definido como STRING, defina o comprimento mínimo do valor do parâmetro. Se Parameter Type estiver definido como NUMBER, defina o valor mínimo do parâmetro.
      Example	Exemplo de valor para o parâmetro.
      Description	Descrição do parâmetro.

6. Clique em Next para prosseguir Configurar configurações de back-end.

Configurar configurações de back-end

O APIG permite que você defina várias políticas de back-end para diferentes cenários. As solicitações que atendam às condições especificadas serão encaminhadas para o back-end correspondente. Por exemplo, você pode fazer com que certas solicitações para uma API sejam encaminhadas para um back-end específico especificando o endereço IP de origem nas condições de política do back-end.

Você pode definir no máximo cinco políticas de back-end para uma API, além do back-end padrão.

1. Defina o back-end padrão.

   As solicitações de API que não atenderem às condições de qualquer back-end serão encaminhadas para o back-end padrão.

   Na página Backend Configuration, selecione um tipo de back-end.

   A APIG oferece suporte a back-ends HTTP&HTTPS, FunctionGraph e Mock. Para obter detalhes sobre os parâmetros necessários para definir cada tipo de serviço de back-end, consulte Tabela 4, Tabela 5 e Tabela 6.

   

   • Os back-ends do FunctionGraph podem ser definidos apenas se o FunctionGraph tiver sido implementado no ambiente atual.
   • Se o serviço de back-end não estiver disponível, use o modo Mock para retornar o resultado esperado ao chamador da API para depuração e verificação.

   Tabela 4 Parâmetros para definir um serviço back-end HTTP&HTTPS

   Parâmetro	Descrição
   Load Balance Channel	Determine se deve usar um canal de balanceamento de carga para acessar o serviço de back-end. Se você selecionar Configure, certifique-se de ter criado um canal de balanceamento de carga.
   URL	Um URL consiste em um método, protocolo, canal de balanceamento de carga/endereço de back-end e caminho. Método Selecione GET, POST, DELETE, PUT, PATCH, HEAD, OPTIONS ou ANY. ANY indica que todos os métodos de requisição são suportados. Protocolo HTTP ou HTTPS. O HTTPS é recomendado para a transmissão de dados importantes ou sensíveis. NOTA: O WebSocket é compatível com HTTP e HTTPS. Este protocolo deve ser o utilizado pelo serviço de back-end. Canal de balanceamento de carga (se aplicável) Selecione um canal de balanceamento de carga. NOTA: Para garantir uma verificação de integridade bem-sucedida e a disponibilidade do serviço, configure os grupos de segurança dos servidores em nuvem em cada canal para permitir o acesso a partir de 100.125.0.0/16. Endereço de back-end (se aplicável) Defina este parâmetro se nenhum canal de balanceamento de carga for usado. Digite um endereço de back-end no formato de "endereço IP do host ou nome de domínio":"número da porta". A porta padrão (80 para HTTP e 443 para HTTPS) será usada se você não especificar uma porta. Portas disponíveis: 1 a 65535. Se você quiser usar uma variável, coloque o nome da variável em sinais numéricos (#), por exemplo, #ipaddress#. Você pode usar múltiplas variáveis, por exemplo, #ipaddress##test#. NOTA: Gateways dedicados criados após 30 de outubro de 2022 podem transmitir a indicação de nome do servidor (SNI) para serviços de back-end durante o handshake TLS. Caminho O caminho de solicitação (URI) do serviço de back-end. Certifique-se de que todos os parâmetros no caminho estejam entre chaves ({}). Por exemplo, /getUserInfo/{userId}. Se o caminho contiver uma variável de ambiente, coloque a variável de ambiente em sinais numéricos (#), por exemplo, /#path#. Você pode usar várias variáveis de ambiente, por exemplo, /#path##request#.
   Host Header (if applicable)	Defina esse parâmetro somente se um canal de balanceamento de carga for usado. Defina um cabeçalho de host para as solicitações a serem enviadas aos servidores de nuvem associados ao canal de balanceamento de carga. Por padrão, o cabeçalho do host original em cada solicitação é usado.
   Timeout (ms)	Tempo limite de solicitação de back-end. Se ocorrer um erro de tempo limite de back-end durante a depuração da API, aumente o tempo limite para localizar o motivo. NOTA: Modifique o tempo limite máximo fazendo referência a Configuração de parâmetros. O intervalo de valores é de 1 ms a 600.000 ms.
   Retries	O valor desse parâmetro não pode exceder o número de serviços de back-end no canal de balanceamento de carga.
   Two-Way Authentication	Determine se deve usar o certificado configurado usando backend_client_certificate para autenticação de cliente. Se ativar esta opção, certifique-se de que configurou um certificado na página Parameters do gateway.
   Backend Authentication	Determine se seu serviço de back-end precisa autenticar solicitações de API. Se você habilitar essa opção, selecione um autorizador personalizado para autenticação de back-end. Autorizadores personalizados são funções criadas no FunctionGraph para implementar uma lógica de autenticação ou invocar um serviço de autenticação. NOTA: A autenticação de back-end depende do FunctionGraph e só está disponível em determinadas regiões.

   Tabela 5 Parâmetros para definir um serviço de back-end do FunctionGraph

   Parâmetro	Descrição
   Function Name	Exibido automaticamente quando você seleciona uma função.
   Function URN	Identificador da função. Clique em Select para especificar uma função.
   Version/Alias	Selecione uma versão de função ou alias. Para obter detalhes, consulte as seções "Gerenciamento de versões" e "Gerenciamento de aliases" no Guia de usuário do FunctionGraph.
   Invocation Mode	Synchronous: ao receber uma solicitação de invocação, o FunctionGraph processa imediatamente a solicitação e retorna um resultado. O cliente fecha a conexão uma vez que recebeu uma resposta do back-end. Asynchronous: os resultados de invocação de função de solicitações de clientes não importam para os clientes. Quando recebe uma solicitação, o FunctionGraph a enfileira, retorna uma resposta e processa uma a uma no estado ocioso.
   Timeout (ms)	Tempo limite de solicitação de back-end. Para mais detalhes, consulte Tabela 4.
   Backend Authentication	Para obter detalhes, consulte a descrição sobre autenticação de back-end em Tabela 4.

   Tabela 6 Parâmetros para definição de um serviço de back-end Mock

   Parâmetro	Descrição
   Status Code	Este parâmetro só está disponível depois de actualizar o componente Shubao.
   Response	Você pode usar o Mock para desenvolvimento, depuração e verificação de APIs. Ele permite que o APIG retorne uma resposta sem enviar a solicitação para o back-end. Isso é útil se você precisar testar APIs quando o back-end não estiver disponível.
   Backend Authentication	Para obter detalhes, consulte a descrição sobre autenticação de back-end em Tabela 4.
   Header Parameters	Cabeçalhos de resposta da API. Clique em Add Header e insira o nome do parâmetro, o valor e a descrição.

   

   • As APIs cujos URLs contenham variáveis não podem ser depuradas na página depuração da API.
   • Para variáveis definidas em URLs de APIs, variáveis de ambiente correspondentes e seus valores devem ser configurados. Caso contrário, as APIs não podem ser publicadas porque não haverá valores que possam ser atribuídos às variáveis.
   • O nome da variável faz distinção entre maiúsculas e minúsculas.

2. (Opcional) Configure parâmetros de back-end para mapeá-los para os parâmetros de solicitação definidos nos locais correspondentes. Se nenhum parâmetro de solicitação estiver definido em 5.c, pule esta etapa.
   1. Na área Backend Parameters, adicione parâmetros de uma das seguintes maneiras:
      • Clique em Import Request Parameter para sincronizar todos os parâmetros de solicitação definidos.
      • Clique em Add Backend Parameter Mapping para adicionar um parâmetro de back-end.
   2. Modifique os mapeamentos (consulte Figura 1) com base nos parâmetros e em suas localizações nas solicitações de back-end.
      Figura 1 Configurar parâmetros de back-end
      
      1. Se a localização do parâmetro for definido como PATH, o nome do parâmetro deverá ser o mesmo definido no caminho de solicitação do back-end.
      2. O nome e o local de um parâmetro de solicitação podem ser diferentes daqueles do parâmetro de back-end mapeado.
         

         • O nome do parâmetro não diferencia maiúsculas de minúsculas. Não pode começar com x-apig- ou x-sdk-.
         • O nome do parâmetro não pode ser x-stage.
         • Se você definir a localização do parâmetro como HEADER, verifique se o nome do parâmetro não começa com um sublinhado (_).
      3. Na figura anterior, os parâmetros test01 e test03 estão localizados nas posições de caminho e consulta das solicitações da API e seus valores serão recebidos no cabeçalho das solicitações de back-end. O test02 está localizado no cabeçalho das solicitações da API, e seu valor será recebido através do test05 no caminho das solicitações de back-end.

         Suponha que test01 é aaa, test02 é bbb e test03 é ccc.

         A solicitação da API é a seguinte:

         curl -ik -H 'test02:bbb' -X GET https://example.com/v1.0/aaa?test03=ccc

         Solicitação de back-end:

         curl -ik -H 'test01:aaa' -H 'test03:ccc' -X GET https://example.com/v1.0/bbb

3. (Opcional) Configure parâmetros constantes para o back-end padrão para receber constantes que são invisíveis para os chamadores da API. Ao enviar uma solicitação para o serviço de back-end, o APIG adiciona esses parâmetros aos locais especificados na solicitação e, em seguida, envia a solicitação para o serviço de back-end.
   Na área Constant Parameters, clique em Add Constant Parameter.

   Tabela 7 Configuração de parâmetro constante

   Parâmetro	Descrição
   Constant Parameter Name	Se Parameter Location for definido como PATH, o nome do parâmetro deve ser o mesmo que no Path. NOTA: O nome do parâmetro não faz distinção entre maiúsculas e minúsculas. Não pode ser x-stage ou começar com x-apig- ou x-sdk- Se Parameter Location for definido como HEADER, o nome do parâmetro não diferencia maiúsculas de minúsculas e não pode começar com um sublinhado (_).
   Parameter Location	Especifique o local do parâmetro constante nas solicitações de serviço de back-end. As opções incluem PATH, HEADER e QUERY.
   Parameter Value	Valor do parâmetro constante.
   Description	Descrição sobre o parâmetro constante.

   

   • O APIG envia solicitações contendo parâmetros constantes para um serviço de back-end após a codificação percentual de valores de parâmetros especiais. Certifique-se de que o serviço de back-end ofereça suporte à codificação de porcentagem. Por exemplo, o valor do parâmetro [api] torna-se %5Bapi%5D após a codificação por cento.
   • Para valores de parâmetros de caminho, APIG percentual codifica os seguintes caracteres: códigos ASCII 0-31 e 127-255, espaços e outros characters especiais ?></%#"[\]^`{|}
   • Para valores de cadeias de consulta, APIG percentual codifica os seguintes caracteres: códigos ASCII 0–31 e 127–255, espaços e outros caracteres especiais >=<+&%#"[\]^`{|}

4. (Opcional) Configure os parâmetros do sistema para que o back-end padrão receba parâmetros de gateway padrão, parâmetros de autenticação de front-end e parâmetros de autenticação de back-end. Ao enviar uma solicitação para o serviço de back-end, o APIG adiciona esses parâmetros aos locais especificados na solicitação e, em seguida, envia a solicitação para o serviço de back-end.
   1. Na área System Parameters, clique em Add System Parameter.

      Tabela 8 Configuração do parâmetro do sistema

      Parâmetro	Descrição
      System Parameter Type	Opções: Default gateway parameter: parâmetros suportados pelo APIG. Frontend authentication parameter: parâmetros a serem exibidos no resultado de autenticação personalizada do front-end. Essa opção estará disponível somente se você tiver definido o Authentication Mode como Custom em Configurar configurações de front-end. Backend authentication parameter: parâmetros a serem exibidos no resultado de autenticação personalizada do back-end. Esta opção só está disponível se tiver ativado a autenticação de back-end no Configurar configurações de back-end.
      System Parameter Name	Nome do parâmetro do sistema. Se System Parameter Type for Default gateway parameter, selecione qualquer um dos seguintes parâmetros. sourceIp: endereço IP de origem de um chamador da API stage: ambiente no qual a API é chamada apiId: ID da API appId: ID da aplicação que chama a API requestId: ID da solicitação gerada quando a API é chamada serverAddr: endereço IP do servidor de gateway serverName: nome do servidor de gateway handleTime: tempo de processamento da solicitação da API providerAppId: ID da credencial do provedor da API apiName: nome da API. Esse parâmetro fica disponível somente após a publicação da API. appName: nome da credencial usada para chamar a API Se System Parameter Type estiver Frontend authentication parameter ou Backend authentication parameter, insira um parâmetro que tenha sido definido para resultados de autenticação personalizados. Para obter detalhes sobre como criar uma função de autorizador personalizada e obter parâmetros de resultado, consulte Guia de desenvolvedor.
      Backend Parameter Name	Nome de um parâmetro de back-end para mapear o parâmetro do sistema. NOTA: O nome do parâmetro não faz distinção entre maiúsculas e minúsculas. Não pode ser x-stage ou começar com x-apig- ou x-sdk- Se Parameter Location for definido como HEADER, o nome do parâmetro não diferencia maiúsculas de minúsculas e não pode começar com um sublinhado (_).
      Backend Parameter Location	Especifique o local do parâmetro de back-end nas solicitações de serviço de back-end. As opções incluem PATH, HEADER e QUERY.
      Description	Descrição sobre o parâmetro do sistema.

5. (Opcional) Adicione uma política de back-end.

   Você pode adicionar políticas de back-end para encaminhar solicitações para diferentes serviços de back-end.

   1. Clique em para adicionar uma política de back-end.
   2. Definir parâmetros de política descritos em Tabela 9. Para obter detalhes sobre outros parâmetros, consulte Tabela 4, Tabela 5 e Tabela 6.

      Tabela 9 Parâmetros de política de back-end

      Parâmetro	Descrição
      Name	O nome da política de back-end.
      Effective Mode	Any condition met: a política de back-end entra em vigor se alguma das condições da política tiver sido cumprida. All conditions met: a política de back-end entra em vigor somente quando todas as condições da política forem atendidas.
      Policy Conditions	Condições que devem ser atendidas para que a política de back-end entre em vigor. Estabeleça condições referindo-se a Tabela 10.

      Tabela 10 Configuração da condição de política

      Parâmetro	Descrição
      Source	Endereço IP de origem: endereço IP a partir do qual a API é chamada Parâmetro de solicitação: um parâmetro de solicitação definido para a API Cookie: cookies de uma solicitação de API Parâmetro do sistema: um parâmetro do sistema que define o tempo de execução do sistema para a API AVISO: Os parâmetros de solicitação (por exemplo, cabeçalhos) definidos como condições de política já devem ter sido definidos para a API. Se System parameter não for exibido, entre em contato com o suporte técnico para atualizar o gateway.
      Parameter Name	Ao definir o Source como Request parameter, selecione um parâmetro de solicitação. Ao definir o Source para System parameter, selecione um parâmetro do sistema. reqPath: URI de solicitação, por exemplo, /a/b/c. reqMethod: método de solicitação, por exemplo, GET. Ao definir Source como Cookie, insira o nome de um parâmetro de cookie.
      Parameter Location	A localização do parâmetro é exibida somente se você definir Source para Request parameter.
      Condition Type	Este parâmetro só é necessário se você definir o Source para Request parameter, System parameter ou Cookie. Equal: o parâmetro de solicitação deve ser igual ao valor especificado. Enumerated: o parâmetro de solicitação deve ser igual a qualquer um dos valores enumerados. Matching: o parâmetro de solicitação deve ser igual a qualquer valor da expressão regular. NOTA: Ao definir o Source para System parameter e selecionar um parâmetro chamado reqMethod, você pode definir o tipo de condição apenas como Equal ou Enumerated.
      Condition Value	Se Condition Type estiver Equal, insira um valor. Se Condition Type estiver Enumerated, insira vários valores e separe-os com vírgulas (,). Se Condition Type for Matching, insira um intervalo de valores, por exemplo, [0-5]. Se Source for Source IP address, digite um ou mais endereços IP e separe-os com vírgulas (,).

6. Definição de respostas.
   Na área Responses, defina as respostas de exemplo.

   Tabela 11 Definição de respostas

   Parâmetro	Descrição
   Example Success Response	A resposta a ser retornada quando a API é chamada com sucesso.
   Example Failure Response	A resposta a ser retornada quando a API não é chamada.

7. Clique em Finish. Você pode ver os detalhes da API na página APIs exibida.

(Opcional) Criação de uma política

Você pode criar políticas para a API depois de publicá-la.

1. Na página APIs, clique em Create Policy.
2. Selecione um tipo de política e defina parâmetros.
   • Selecionar política existente
   • Criar nova política (consulte Criação de uma política)

3. Clique em OK.

Perguntas frequentes sobre a criação de APIs

O APIG oferece suporte a vários pontos de extremidade de back-end?

Como escolher um modo de autenticação?

Quais são as possíveis causas se um serviço de back-end falhar ao ser chamado ou se a chamada expirar?

Por que estar vendo a mensagem "Nenhum back-end disponível"?

Operações de acompanhamento

Depois de criar uma API, verifique-a seguindo o procedimento em Depuração de uma API.