DataWorks:Teste, publicação e gerenciamento de versões de API

Testar uma API em desenvolvimento

Testar uma API em desenvolvimento significa realizar o teste na página Service Development (o ambiente de desenvolvimento). Antes de testar a API, gere-a no modo assistente ou no modo script, ou registre um service existente como uma API.

Procedimento:

1. Faça logon no console do DataWorks. Na região de destino, clique em Data Analysis and Service > DataService Studio no painel de navegação à esquerda. Selecione um workspace na lista suspensa e clique em Go to DataService Studio.

2. Na lista de APIs à esquerda, clique duas vezes no nome da API que deseja testar para abrir sua página de edição.

3. Na página de edição da API, localize e clique no botão Test para abrir a caixa de diálogo Test APIs.

4. No painel esquerdo da caixa de diálogo, insira um valor de teste para cada parâmetro de solicitação.

5. Clique em Start Test para acionar a chamada da API.

Visualizar resultados do teste:

Após a conclusão do teste, visualize as seguintes informações no painel direito da caixa de diálogo:

• Request Details: As informações completas da solicitação para a chamada da API, incluindo o caminho da solicitação, cabeçalhos e corpo. Utilize estas informações para verificar se a solicitação está estruturada corretamente.

• Response Details: Os dados de resposta da API (o resultado real da consulta). Compare este resultado com o esperado para validar a lógica da API.

• Response Duration: A latência de resposta de ponta a ponta da solicitação da API. Caso a latência esteja alta, considere otimizar a lógica de consulta ou a configuração da source de dados.

Se o teste falhar, analise cuidadosamente a mensagem de erro retornada, faça as modificações necessárias e teste novamente.

Testar uma API publicada

Testar uma API publicada significa realizar o teste na página Service Management (o ambiente de produção). Isso verifica o comportamento real da API em tempo de execução após a publicação. Antes de executar este teste, publique a API.

Procedimento:

1. Na página Data Services, clique em Service Management na barra de navegação superior.

2. No painel de navegação à esquerda, clique em Test APIs.

3. Na lista suspensa, selecione a API que deseja testar e certifique-se de que os valores dos parâmetros de solicitação estejam totalmente configurados.

4. Clique em Start Test e visualize os Request Details e Response Details no painel direito.

Observações:

• A página Test APIs fornece apenas a funcionalidade de teste de API online. Ela não permite atualizar o exemplo de resposta normal de uma API.

• Caso a Pagination for Return Results esteja configurada para uma API, a ordenação dos dados retornados depende do comportamento da source de dados subjacente. Se precisar de classificação, configure um Sort field para a API no modo assistente ou adicione uma cláusula ORDER BY ao código SQL no modo script.

Interpretação de resultados de teste e sugestões de otimização

Um resultado completo de teste de API consiste em três partes. Compreender cada parte ajuda a identificar problemas rapidamente:

Depois que os resultados do teste atenderem às expectativas, prossiga com a publicação da API no API Gateway.

Pré-requisitos

Antes de publicar uma API, garanta que as seguintes condições sejam atendidas:

• API Gateway ativado: Ative o service no console do API Gateway.

  Importante

  Devido a limitações de arquitetura de rede entre o DataWorks e o API Gateway, ao adquirir uma instância do API Gateway, apenas instâncias dedicadas tradicionais são suportadas para o Instance Type. Instâncias integradas à VPC não são suportadas.

• Grupo de API criado: Durante a publicação, a API é implantada no grupo correspondente no API Gateway com base na associação do workflow. Certifique-se de que o workflow esteja corretamente associado a um grupo do API Gateway. É possível verificar o nome do grupo clicando com o botão direito em Workflow > Change.

Processo de publicação

A publicação da API segue um processo de três etapas: Enviar → Aprovação → Publicar:

Etapa 1: Enviar a API

1. Acesse a página Data Services. Na página Service Development, clique duas vezes no nome da API que deseja publicar na lista de APIs para abrir sua página de edição.

2. Clique no botão Submission no canto superior direito.

3. Após o envio bem-sucedido, o sistema gera automaticamente uma versão da API (como V1 ou V2). Visualize o status da versão no painel Version que aparece à direita.

Etapa 2: Solicitar publicação e aguardar aprovação

1. No painel Version à direita, localize a versão da API a ser publicada e clique no botão Publish.

2. Siga as instruções na tela para inserir o motivo da solicitação e clique em Requested Permissions para enviar a solicitação de publicação.

3. Caso o workspace tenha um processo de aprovação configurado, a solicitação de publicação deve ser aprovada na central de aprovações. O aprovador pode visualizar os detalhes da solicitação e processar a aprovação na página Approval Center > To Be Processed.

4. Após a concessão da aprovação, o status da API no painel Version muda de To Be Requested para Can Be Published.

Se o workspace não tiver um processo de aprovação configurado, prossiga diretamente para a etapa de publicação após o envio, sem aguardar aprovação. Para obter mais informações, consulte Configurar um processo de aprovação.

Etapa 3: Executar a publicação

1. Após a concessão da aprovação, na barra de navegação lateral direita da página de edição da API, clique em Version e localize a versão da API com o status Can Be Published.

2. Clique no botão Publish e aguarde até que o sistema indique que a publicação foi bem-sucedida.

3. Depois que a API é publicada, o DataWorks a implanta no grupo correspondente no API Gateway com base no grupo associado do workflow ao qual a API pertence.

Verificação pós-publicação

Após a publicação, verifique e gerencie a API das seguintes maneiras:

• Visualizar no API Gateway: Faça logon no console do API Gateway. Visualize as informações da API publicada em Manage APIs > Service List e configure políticas como limitação de taxa e controle de acesso.

• Chamadas de aplicação: Se a API for chamada por sua própria aplicação, crie uma aplicação no API Gateway, autorize a API para a aplicação e use AppKey e AppSecret para chamadas assinadas e criptografadas. O API Gateway também fornece SDKs para as principais linguagens de programação. Para obter mais informações, consulte Autorizar e chamar uma API. Para integração de SDK, consulte Integração de SDK.

• Alteração de protocolo: Para uma API publicada, na aba Service Management > Published APIs, clique em More > Change Protocol para a API correspondente a fim de modificar o protocolo de acesso (por exemplo, de HTTP para HTTPS). A alteração do protocolo entra em vigor imediatamente. No entanto, se o protocolo original for removido, as chamadas de API que utilizam esse protocolo falharão. Proceda com cautela.

Listar no Alibaba Cloud API Marketplace (opcional)

O Alibaba Cloud API Marketplace abrange múltiplas categorias e pode ajudar você a monetizar seus dados.

Depois que as APIs geradas ou registradas no Data Service forem publicadas no API Gateway, liste-as no Alibaba Cloud API Marketplace para venda com um clique, ajudando as empresas a monetizar o valor dos dados.

Pré-requisitos:

• Apenas identidades corporativas são suportadas para registro no Alibaba Cloud API Marketplace.

• Antes de listar, registre-se no Alibaba Cloud Marketplace como provedor de services. Para conhecer o processo, consulte Registrar-se como provedor de services.

Procedimento:

1. Acesse a Plataforma de Provedores de Services da Alibaba Cloud.

2. No painel de navegação à esquerda, clique em Commodity > Product Management.

3. Clique em Publish Product.

4. Na página Access Information, configure os parâmetros conforme instruído (incluindo o nome do product, estratégia de preços e vinculação da API) para concluir o processo de listagem da API.

Visualizar histórico de versões

1. Faça logon no console do DataWorks. Na região de destino, clique em Data Analysis and Service > DataService Studio no painel de navegação à esquerda. Selecione um workspace na lista suspensa e clique em Go to DataService Studio.

2. Na página Service Development, clique duas vezes no nome da API que deseja visualizar na lista de APIs para abrir sua página de edição.

3. Clique no botão Version no lado direito da página para abrir o painel de versões e visualizar as informações e detalhes das versões. O painel de versões exibe todas as informações de versões históricas da API atual, incluindo:

   Nota

   Cada versão fornece um link API Details na coluna Actions. Clique nele para visualizar as informações completas de configuração dessa versão, incluindo parâmetros de solicitação, parâmetros de resposta e configuração da source de dados.

   Coluna	Descrição
   API ID	O identificador exclusivo da API atual.
   Version	O número da versão, que incrementa na ordem de envio (V1, V2, V3 e assim por diante).
   Submitted By	O usuário que enviou esta versão.
   Submitted At	O horário de publicação desta versão, com precisão de segundos.
   Status	Publish (a versão mais recente atualmente em vigor online) Can Be Published (uma versão que passou nos testes e foi enviada) Batch Synchronization (uma versão histórica antiga)

Comparação de versões

Após múltiplas iterações de uma API, compare as versões para entender as alterações específicas.

Procedimento:

1. No painel Version, selecione quaisquer duas versões que deseja comparar.

2. Clique no botão Compare na parte inferior do painel.

3. Na caixa de diálogo History Version Contrast que aparece, visualize as diferenças entre as duas versões.

Conteúdo da comparação:

• API em modo assistente: Exibe diferenças nos parâmetros de solicitação e resposta, incluindo alterações em atributos como nome do parâmetro, tipo e se um parâmetro é obrigatório.

• API em modo script: Exibe diferenças de texto em scripts SQL, com linhas adicionadas, excluídas e modificadas destacadas.

A comparação de versões é especialmente útil em cenários de colaboração em equipe, ajudando os revisores a entender rapidamente o conteúdo de cada alteração.

Reversão de versão

Quando uma nova versão apresenta anomalias ou não atende às expectativas, reverta a API para uma versão estável anterior.

Procedimento:

1. No painel Version, localize a versão histórica de destino.

2. Clique no botão Roll Back na coluna Actions dessa versão.

3. Na caixa de diálogo Confirm Rollback que aparece, clique em Confirm.

Após a conclusão da reversão, a configuração da API é restaurada para o conteúdo da versão histórica selecionada, e a versão online atual é atualizada imediatamente. Recomendamos o uso do recurso de comparação de versões para confirmar a configuração da versão de destino antes de realizar uma reversão, evitando alterações não intencionais.

Estratégia de gerenciamento de versões

Boas práticas de gerenciamento de versões reduzem significativamente o risco de incidentes de produção.

• Registros de alterações: Sempre que enviar uma versão, descreva claramente as alterações e os motivos nas notas de envio para que os membros da equipe possam entender o contexto através da comparação de versões.

• Verificação de lançamento gradual: Para alterações importantes, recomendamos a verificação completa no ambiente de teste antes da publicação no ambiente de produção.

• Reversão rápida: Quando um problema for detectado online, use a reversão de versão para restaurar o service primeiro e depois investigue a causa raiz. A reversão é mais rápida do que modificar e republicar, minimizando o impacto nos negócios.

• Limpeza regular: Para APIs que não foram usadas por um longo período, despublique-as e limpe-as prontamente para reduzir a complexidade de gerenciamento e potenciais riscos de segurança.

Workflow de colaboração para teste e publicação

Em cenários de colaboração em equipe, o seguinte workflow é recomendado:

1. Os desenvolvedores criam e configuram a API na página Service Development.

2. Os desenvolvedores testam a API no ambiente de desenvolvimento para verificar a funcionalidade.

3. Os desenvolvedores enviam a API para gerar uma nova versão e iniciam uma solicitação de publicação.

4. Os aprovadores revisam a solicitação de publicação na central de aprovações e podem usar o recurso de comparação de versões para visualizar as alterações.

5. Após a aprovação, os desenvolvedores executam a operação final de publicação.

6. Os operadores realizam testes online e monitoramento da API publicada na página Service Management.

7. Se problemas forem encontrados, restaure rapidamente a API através da reversão de versão ou despublique-a para reparo.

Este workflow ajuda as equipes a alcançar um gerenciamento eficiente de API de ciclo de vida completo, garantindo a qualidade da publicação.

Limitações dos exemplos de resposta

A página de edição da API suporta a definição de um exemplo de resposta normal para exibir a estrutura de dados de resposta esperada na documentação da API. Observe o seguinte:

• Sem sincronização automática: Os resultados de teste da página de teste de API não são atualizados automaticamente como o exemplo de resposta normal. Edite ou cole manualmente o exemplo de resposta na página de edição da API.

• Limite de tamanho: O exemplo de resposta normal possui um limite máximo de caracteres. Se os dados do exemplo forem muito grandes (por exemplo, contendo centenas de registros), o salvamento pode falhar. Mantenha apenas 2 a 3 registros típicos como exemplo.

• Entra em vigor após a publicação: Após modificar o exemplo de resposta normal, reenvie e publique a API para que as alterações tenham efeito na documentação do API Gateway.

Tratamento de alterações na estrutura da tabela da source de dados

Quando a estrutura da tabela da source de dados associada a uma API muda (como adição de colunas, exclusão de colunas ou modificação de tipos de colunas), as APIs publicadas não detectam essas alterações automaticamente. Se não tratadas, os seguintes problemas podem ocorrer:

Procedimento:

1. Acesse a página de edição da API e modifique a configuração da API com base nas alterações da estrutura da tabela.

   1. Modo assistente: Reselecione a tabela, e o sistema atualizará automaticamente a lista de colunas.

   2. Modo script: Modifique manualmente os nomes das colunas ou o nome da tabela na instrução SQL.

2. Após salvar a configuração, teste novamente para verificar as alterações.

3. Envie e republice a API.

Para APIs em modo assistente, após a clonagem, se a estrutura da tabela associada à API original tiver sido alterada, a API clonada ainda poderá usar as informações antigas da estrutura da tabela. Recomendamos entrar novamente no modo assistente para atualizar a configuração das colunas após a clonagem.