1. Crie uma instância de gateway

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

1. Faça login 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: Os modelos Pay-as-you-go e Subscription são suportados. 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 serviço de backend posteriormente.

   • Zone Selection: Escolha 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. Quando o status da instância mudar para Running, ela estará criada.

Criar uma instância de gateway .

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.

O 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. Verifique se a região no topo corresponde à da instância de 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 registro ICP.

   • 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.

Adicionar um nome de domínio .

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. Certifique-se de que a região no topo esteja 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.

Criar uma 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, vá para 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

     Após associar um workflow 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. Ao escolher GET, 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 Criar uma api no modo script.

3. Configure a api

Na página de edição da api, siga o processo Select Table > Select Parameters > Configure Parameters para definir a lógica da api.

1. Selecionar 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.

   • Ao usar uma fonte de dados MaxCompute, configure o Acceleration Method para melhorar o desempenho.

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

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

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

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

3. Configurar 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 facilita os testes subsequentes.

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

4. Configurar grupo de recursos de serviço 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, na lista suspensa, um grupo de recursos associado ao workspace atual.

   • Environment Configuration:

     • Timeout: 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: Número máximo de registros retornados por uma única chamada de api, como 2000.

5. Configurar autenticação de segurança

   Configure a autenticação de segurança no lado direito da página. Após ativar a autenticação de consumidor, selecione um dos seguintes tipos 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 adiciona credenciais às solicitações em um formato especificado, 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 com segurança entre cliente e servidor. Permite 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.	Projetado para cenários com altos requisitos de integridade de dados e prevenção contra adulteração.

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

1. Testar a api

A 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. Use a Response Duration para avaliar o desempenho.

4. Se o teste falhar, verifique as configurações da 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 bem-sucedido, o sistema gera automaticamente uma versão da api. Visualize-a na aba Version Management no lado direito.

3. Se houver um processo de aprovação 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. Após a aprovação pelo responsável, o status muda 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 de gateway for a mesma que a VPC do grupo de recursos do DataWorks, selecione Default.

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

       Criar um serviço de backend

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

       Um serviço de backend estabelece a conectividade entre duas VPCs diferentes para solicitações do Serviço de Dados.

       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 serviço, configure o nome do serviço e associe-o à source criada.

       Criar um serviço de backend .

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 essa operação para implantar a mesma api em diferentes instâncias de gateway.

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

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

Após a implantação de uma api em várias instâncias de gateway, a exibição na página Service Management muda da seguinte forma.