1. Crie uma instância de gateway

Uma instância de gateway é o mecanismo que processa as solicitações de API.

1. Faça logon no console do Cloud-native API Gateway. No painel de navegação à esquerda, clique em Instance.

2. Selecione uma região na barra de navegação superior.

   Importante

   A região deve ser a mesma do seu workspace do DataWorks.

3. Na página Instance, clique em Create Instance.

4. Na página de compra, configure os seguintes parâmetros:

   • Commodity Type: Há suporte para Pay-as-you-go e Subscription. Para testes, selecione pagamento conforme o uso.

   • Gateway Name: Insira um nome personalizado fácil de identificar, como dataservice-prod.

   • Gateway Specification: Selecione nó único para testes ou vários nós para conformidade com SLA de produção.

   • Network Access Type: Selecione Public ou Public + Private para ativar o acesso à Internet. O uso de acesso público gera taxas de tráfego.

   • VPC: Selecione uma VPC.

     Importante

     Recomendamos fortemente o uso da mesma VPC do grupo de recursos serverless mencionado nos pré-requisitos. Se as VPCs forem diferentes, será necessário criar manualmente um service de backend posteriormente.

   • Zone Selection: Selecione Auto Assign ou atribua manualmente instâncias em diferentes zonas e vSwitches.

   • Resource Group: Selecione um grupo de recursos com base na sua política de gerenciamento de recursos.

5. Clique em Buy Now e conclua o pagamento. A criação da instância leva cerca de 1 a 5 minutos. A instância estará pronta quando seu status mudar para Running.

Create a gateway instance .

2. Adicionar um nome de domínio

Se você precisar acessar a API apenas dentro de uma VPC, não será necessário solicitar um nome de domínio.

Um nome de domínio serve como ponto de entrada de acesso público para a API.

1. No painel de navegação à esquerda do console do Cloud-native API Gateway, clique em Domain Name. Certifique-se de que a região no topo corresponda à instância do gateway.

2. Clique em Add Domain Name e configure as seguintes informações:

   • Domain Name: Insira seu próprio nome de domínio, como api.example.com. Nomes de domínio independentes usados em regiões da China devem concluir o ICP filing.

   • Protocol: Selecione HTTPS para transmissão segura de dados. Você também deve selecionar um certificado SSL existente.

   • Other Settings: Ative Force HTTPS e Enable HTTP/2, e selecione uma TLS Version com base nos seus requisitos de segurança.

Add a domain name .

3. Crie uma REST API

Uma REST API agrupa APIs sob um Base Path compartilhado. Um workflow do DataWorks se vincula a uma REST API.

Em comparação com o API Gateway legado, uma REST API equivale a um grupo de APIs.

1. No painel de navegação à esquerda do console do Cloud-native API Gateway, clique em API. Verifique se a região no topo está correta.

2. Clique em Create API. Na página Create API, selecione Create no cartão REST API.

3. No painel Create REST API, configure as seguintes definições:

   • API Name: Nomeie sua coleção de APIs. O nome deve ser globalmente exclusivo na região atual, como dataservice-user-api.

   • Base Path: O caminho base da API, que faz parte da URL. Por exemplo, defina-o como /v1. O caminho de acesso final será Protocol://DomainName/BasePath/APIPath.

   • Version Management: Ative conforme necessário.

Create a REST API .

1. Crie um workflow

Um workflow organiza APIs relacionadas e as associa a uma REST API no API Gateway.

1. Acesse o console do DataWorks. No painel de navegação à esquerda, acesse Data Services > Service Development.

2. Clique no ícone de criação no canto superior esquerdo e selecione Create Workflow.

3. Na caixa de diálogo Create Workflow, configure as seguintes definições:

   • Workflow Name: Insira um nome personalizado exclusivo dentro do workspace, como User Query Workflow. O nome deve ter entre 4 e 50 caracteres.

   • Gateway Type: Selecione Cloud-native API Gateway.

   • REST API: Na lista suspensa, selecione a REST API criada na Etapa 1 (por exemplo, dataservice-user-api). Se ela não aparecer, clique no botão Refresh.

     Importante

     Depois que um workflow é associado a uma REST API, o vínculo não pode ser alterado. Prossiga com cautela.

2. Gerar uma API no modo assistente

1. Na página Service Development, passe o mouse sobre o ícone de criação no canto superior esquerdo e clique em Create API > Generate API.

2. Na caixa de diálogo Generate API, selecione Wizard Mode e configure as informações básicas da API:

   • Location: Selecione o Workflow criado na etapa anterior (User Query Workflow).

   • API Name: Insira um nome para a API específica, como Query User by User ID.

   • APIPath: O caminho específico da API, como /user/info. Ele é concatenado ao Base Path para formar o caminho completo da URL. O API Path deve começar com / e não pode exceder 200 caracteres.

   • Request Method: Selecione GET ou POST. Quando GET é selecionado, os parâmetros de solicitação só podem ser colocados na string QUERY.

   • Response Type: Selecione JSON.

3. Clique em Create para ir à página gráfica de edição de API.

   Nota

   Para criar uma API no modo script, consulte Create an API in script mode.

3. Configure a API

Na página de edição da API, siga o fluxo Select Table > Select Parameters > Configure Parameters para definir sua API.

1. Selecione uma tabela (fonte de dados e tabela)

   Na seção Select Table no lado esquerdo da página, configure as seguintes definições:

   • Data Source Type: Selecione MaxCompute(ODPS).

   • Data Source Name: Selecione a fonte de dados configurada nos pré-requisitos.

   • Data Table Name: Selecione a tabela user_info.

   • Se você usar uma fonte de dados do MaxCompute, deverá configurar o Acceleration Method para melhorar o desempenho.

2. Selecione parâmetros (solicitação e resposta)

   Após selecionar uma tabela, a seção Select Parameters abaixo lista todas as colunas da tabela.

   • Configure parâmetros de solicitação: Selecione a coluna user_id e clique em Set as Req Param.

   • Configure parâmetros de resposta: Selecione as colunas user_id e user_name e clique em Set as Resp Param.

4. Configure detalhes do parâmetro de solicitação: Na aba Request Parameters no lado direito da página, defina o Sample Value para o parâmetro user_id (por exemplo, 10001). Isso ajuda nos testes subsequentes.

   Melhor prática : Defina colunas indexadas como parâmetros de solicitação para otimizar o desempenho da consulta.

5. Configure grupo de recursos de service e ambiente

   Na seção Service Resource Group no lado direito da página, configure as seguintes definições:

   • Resource Group Type: Selecione Exclusive Resource Group for Data Service e escolha um grupo de recursos associado ao workspace atual na lista suspensa.

   • Environment Configuration:

     • Timeout: O tempo máximo que o Cloud-native API Gateway aguarda por uma resposta do DataWorks, como 3 segundos.

     • Maximum Number of Data Records for a Single Request: O número máximo de registros retornados por uma única chamada de API, como 2000.

7. Configure autenticação de segurança

   Na seção de autenticação de segurança à direita, ative a autenticação de consumidor e selecione um tipo de autenticação.

   Nota

   O DataWorks cria automaticamente um consumidor com o mesmo nome do workspace no Cloud-native API Gateway. Não é necessário criar um manualmente.

   Método de autenticação	Descrição	Cenário aplicável
   API Key	O cliente inclui credenciais em cada solicitação, e o gateway verifica sua validade e permissões. Adequado para operações não sensíveis. Menos seguro que JWT e HMAC — proteja as credenciais com cuidado.	Indicado para cenários de integração leve e rápida com requisitos moderados de segurança.
   JWT	JSON Web Token (JWT) usa assinaturas HMAC, RSA ou ECDSA para transmitir declarações verificáveis entre cliente e servidor, permitindo verificação de identidade e controle de acesso no gateway.	Recomendado para sistemas distribuídos e cenários de single sign-on (SSO).
   HMAC	O cliente assina o conteúdo da solicitação com uma chave de assinatura e envia a assinatura junto com a solicitação para verificação pelo servidor.	Ideal para cenários com altos requisitos de integridade de dados e prevenção contra adulteração.

8. Salve a API: Após concluir todas as configurações, clique no ícone Save na barra de ferramentas superior.

Etapa 3: Testar, envie e implantar a API

1. Testar a API

Uma API deve passar pelos testes antes de poder ser enviada.

1. Na página de edição da API, clique no botão Test APIs na barra de ferramentas.

2. Na caixa de diálogo Test APIs, insira um valor de amostra existente para o parâmetro de solicitação user_id (por exemplo, 10001) e clique em Start Test.

3. Visualize os Response Details no lado direito para verificar se os dados atendem às expectativas. A Response Duration pode ser usada para avaliar o desempenho.

4. Se o teste falhar, verifique as configurações de fonte de dados, tabela, parâmetros ou grupo de recursos com base na mensagem de erro.

2. Envie a API

Após um teste bem-sucedido, envie a API para gerar uma versão implantável.

1. Na página de edição da API, clique no botão Submission na barra de ferramentas.

2. Após o envio, o sistema gera uma versão da API, visível na aba Version Management no lado direito.

3. Se um processo de aprovação estiver configurado para seu workspace, o status da versão da API será To Be Requested. Clique em Request to Publish para iniciar uma solicitação. Depois que o aprovador autorizar a solicitação, o status mudará para Can Be Published.

   Se nenhum processo de aprovação estiver configurado, o status da versão geralmente será Can Be Published diretamente.

3. Implantar a API no Cloud-native API Gateway

Implante a API no ambiente de produção.

1. Na aba Version no lado direito da página de edição da API, localize a versão com o status Can Be Published e clique em Publish na coluna Actions.

2. Na caixa de diálogo Publish API to Cloud-native API Gateway, configure as três definições obrigatórias a seguir:

   • Domain Name: Selecione o nome de domínio adicionado na Etapa 1.

     Importante

     Todas as APIs sob a mesma REST API compartilham o mesmo nome de domínio. Alterar o nome de domínio durante a implantação afetará o nome de domínio usado para chamar todas as APIs sob a mesma REST API.

   • Gateway Instance: Selecione a instância de gateway criada na Etapa 1.

   • Backend Service:

     • Se a VPC da instância do gateway for a mesma que a VPC do grupo de recursos do DataWorks, selecione Default.

     • Se as VPCs forem diferentes, selecione um service de backend criado no Cloud-native API Gateway.

       Criar um service de backend

       Execute esta etapa apenas se a VPC selecionada ao criar a instância do gateway na Etapa 1 for diferente da VPC do grupo de recursos serverless. Se as VPCs forem iguais, ignore esta seção.

       Um service de backend estabelece a conectividade entre duas VPCs diferentes para solicitações do Data Service.

       1. Na lista de Instance no console do Cloud-native API Gateway, clique no id da instância de destino.

       2. No painel de navegação à esquerda da página de detalhes da instância, clique em Service.

       3. Clique em Create Service. Se solicitado, crie primeiro uma source na aba Source.

       4. Ao criar um service, configure o nome do service e associe-o à source que você criou.

       Create a backend service .

Após a implantação, a API estará ativa e poderá ser chamada na URL de acesso.

Etapa 4: Chamar e verifique a API

Com base no método de autenticação configurado na Etapa 2, use credenciais para acessar a API.

1. Na aba Version da API implantada, localize a versão que você acabou de implantar e clique em Service Management à direita para ir à página de gerenciamento de API e visualizar os detalhes da API.

2. Na página de gerenciamento de API, clique no endereço em API Name/Path para visualizar os detalhes da API.

3. Construir e execute uma chamada

   • URL de amostra: Copie a URL de acesso dos detalhes da API.

   • Informações de autenticação: Acesse Service Management > Call APIs > Cloud-native API Gateway para visualizar os detalhes de autenticação para diferentes métodos.

   • Método de chamada: Use curl ou outro cliente HTTP e inclua o AppKey e o AppSecret no cabeçalho da solicitação para fazer a chamada.

     Call an API .

   Exemplos de chamada com curl:

   Autenticação API Key

   Replace api.example.com with your actual domain name curl "https://api.example.com/v1/user/info?user_id=10001" \ -X GET \ -H "Content-Type: application/json; charset=utf-8" \ -H "Authorization: Bearer <API_KEY>"

   Autenticação HMAC

   Para obter o processo detalhado de chamada, consulte Use HMAC authentication to call an API.

   Replace api.example.com with your actual domain name curl "https://api.example.com/v1/user/info?user_id=10001" \ -X GET \ -H "x-ca-key: Access Key" \ -H "x-ca-signature: <Base64EncodedSignature>" \ -H "x-ca-signature-method: HmacSHA256" \ -H "Date: Wed, 01 Jan 2025 00:00:00 GMT" \ -H "Accept: application/json" \

4. Visualize a resposta esperada: Se tudo funcionar corretamente, você receberá uma resposta JSON semelhante à seguinte:

   {
     "data": {
       "user_id": 10001,
       "user_name": "Alice"
     },
     "success": true
   }

Suporte a múltiplas versões para APIs

O Cloud-native API Gateway permite implantar a mesma API em várias instâncias de gateway, possibilitando direcioná-la para diferentes ambientes (teste vs. produção) ou atender a diferentes necessidades de negócios.

Implantar uma API em várias instâncias de gateway

No painel Version, clique em Publish para a versão com o status Can Be Published. Na caixa de diálogo Publish API to Cloud-native API Gateway, selecione uma Gateway Instance diferente para implantar a API na instância de gateway correspondente. Repita esse processo para implantar a mesma API em várias instâncias.

Nota

Dentro da mesma instância de gateway, a implantação de uma nova versão desimplanta automaticamente a anterior. As versões em diferentes instâncias de gateway são independentes e podem coexistir no estado deployed.

Exibição de múltiplas versões no gerenciamento de service

Depois que uma API é implantada em várias instâncias de gateway, a exibição na página Service Management muda da seguinte forma.

Lista de gerenciamento de API

Na aba Published APIs do Service Management, o mesmo id de API aparece em vários registros — um para cada instância de gateway implantada. A coluna Gateway Instance mostra o nome da instância e o id do gateway para cada registro.

Página de detalhes da API

Clique no nome de uma API para abrir sua página de detalhes. Um seletor de Gateway Instance na parte superior permite alternar entre instâncias para visualizar a URL de acesso, os parâmetros de solicitação e os parâmetros de resposta de cada implantação.