Pré-requisitos: Três elementos essenciais

Antes de chamar qualquer API do Data Service, você deve atender a três pré-requisitos:

A relação entre esses três elementos é a seguinte: a API é a "porta", o aplicativo é o "crachá" e a autorização é o "passe". Você só consegue passar pela porta se apresentar tanto um crachá válido quanto o passe correspondente.

Criar um aplicativo (identidade do aplicativo)

Um aplicativo funciona como contêiner para as credenciais de chamada de API. Cada aplicativo possui um conjunto independente de informações de autenticação (AppKey, AppSecret e AppCode), equivalente a nome de usuário e senha.

Aplicativo padrão criado automaticamente

Ao publicar uma API no DataWorks pela primeira vez, o sistema cria automaticamente um aplicativo com o mesmo nome do workspace no API Gateway e autoriza todas as APIs desse workspace para este aplicativo padrão. Isso significa que:

• Os membros do workspace podem usar as credenciais do aplicativo padrão para chamar APIs sem necessidade de autorização adicional.

• As informações de autenticação do aplicativo padrão podem ser visualizadas na página Call APIs do console do Data Service.

Criar um aplicativo manualmente

Para isolar tráfego ou diferenciar permissões entre diferentes chamadores, crie um novo aplicativo no console do API Gateway:

1. Faça login no console do API Gateway.

2. No painel de navegação à esquerda, selecione Application Management.

3. Clique em Create Application e insira o nome e a descrição do aplicativo.

4. Após a criação do aplicativo, o sistema gera um conjunto de AppKey, AppSecret e AppCode para ele.

Crie aplicativos separados para diferentes cenários de chamada (como sistemas internos, parceiros terceirizados e painéis) para simplificar o monitoramento de tráfego, a limitação de taxa e o gerenciamento de permissões.

Processo de autorização

A autorização concede a um aplicativo a permissão para chamar uma API específica. Somente um aplicativo autorizado consegue chamar a API correspondente com sucesso usando suas credenciais.

Conceder acesso a outras contas

Para disponibilizar uma API para workspaces em outras contas Alibaba Cloud, realize a autorização entre contas:

1. Faça login 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. Acesse a página Data Services, clique em Service Management na barra de menu superior e vá para a página Manage APIs.

3. Na aba Published APIs, localize a API de destino e clique em Authorization na coluna Actions.

4. Na caixa de diálogo API Authorization, configure os seguintes parâmetros:

   

   Parâmetro	Descrição
   API Name	Nome da API a ser autorizada. Este valor não pode ser modificado.
   Alibaba Cloud Account ID to Authorize	ID da conta Alibaba Cloud que receberá permissão para chamar esta API. É possível visualizar o ID da conta na página .
   Authorized Workspace	Selecione o workspace sob a conta Alibaba Cloud de destino.
   Authorization Validity Period	Selecione o período de validade da autorização (veja detalhes abaixo).

5. Clique em Confirm para concluir a autorização.

Período de validade da autorização

O período de validade determina por quanto tempo a parte autorizada poderá chamar a API:

Se uma API autorizada for despublicada ou excluída, a parte autorizada não poderá mais chamá-la. Caso uma API autorizada seja despublicada e republicada posteriormente, ou modificada e republicada, o proprietário da API deverá reautorizar a nova versão.

Visualizar APIs autorizadas e concedidas

Na página Manage APIs, visualize o status de autorização sob duas perspectivas:

Visualizar APIs autorizadas para você (quais APIs tenho permissão para usar)

Clique na aba Authorized to Use para ver todas as APIs que outras contas autorizaram para você. Nesta página, você pode:

• Clicar em Test para testar uma API autorizada online. Para mais informações, consulte Testar uma API.

• Clicar em Delete para renunciar voluntariamente à autorização de chamada de uma API.

Visualizar APIs que você autorizou para outros (quais APIs autorizei para terceiros)

Clique na aba Authorize Others to Use para ver as APIs que você autorizou para outros workspaces. Nesta página, você pode:

• Clicar em Test para testar uma API autorizada online.

• Clicar em Manage para revogar ou modificar a autorização de um workspace específico.

Três cenários de autorização

A granularidade da autorização de API varia conforme o tamanho da equipe e os requisitos de segurança. Os três cenários a seguir abrangem as abordagens mais comuns.

Cenário 1: Mesmo workspace, compartilhando um aplicativo

Descrição do cenário: Todos os membros dentro do mesmo workspace do DataWorks compartilham o aplicativo padrão, criado automaticamente para o workspace, para chamar APIs.

Situação aplicável: Equipe pequena com alta confiança mútua; sem necessidade de diferenciar o tráfego de chamadas por membro individual; início rápido com configuração mínima.

Funcionamento: Quando uma API é publicada, o DataWorks cria automaticamente um aplicativo com o mesmo nome do workspace e autoriza todas as APIs do workspace para este aplicativo. Todos os membros do workspace compartilham o mesmo AppKey, AppSecret e AppCode.

Vantagem: Configuração zero, pronto para uso imediato. Desvantagem: Não é possível identificar qual membro específico iniciou uma chamada; se as credenciais vazarem, todo o workspace será afetado.

Cenário 2: Cada usuário RAM usa um aplicativo independente

Descrição do cenário: Cada usuário RAM (subconta) na organização cria um aplicativo independente no API Gateway e recebe autorização individual para chamar APIs.

Situação aplicável: Necessidade de rastrear com precisão o comportamento de chamada de API de cada usuário; necessidade de definir políticas de limitação diferentes para usuários distintos; altos requisitos de segurança e conformidade que exigem credenciais por usuário.

Funcionamento: Cada usuário RAM faz login no console do API Gateway e cria seu próprio aplicativo; o administrador da API autoriza a API para o aplicativo de cada usuário individualmente; cada usuário chama a API usando as credenciais de seu próprio aplicativo.

Vantagem: Comportamento de chamada rastreável por indivíduo, forte isolamento de segurança e impacto mínimo em caso de vazamento de credenciais. Desvantagem: Maior sobrecarga de gerenciamento; cada novo usuário exige criação de aplicativo e configuração de autorização.

Cenário 3: Múltiplos usuários RAM agrupados, cada grupo compartilhando um aplicativo

Descrição do cenário: Vários usuários RAM são divididos em grupos por função de negócio ou equipe, e os membros de cada grupo compartilham o mesmo aplicativo para chamar APIs.

Situação aplicável: Equipe grande organizada por departamento ou projeto; necessidade de diferenciar o tráfego de chamadas por linha de negócio sem exigir rastreamento por usuário; equilíbrio entre custo de gerenciamento e segurança.

Funcionamento: Crie um número correspondente de aplicativos para cada grupo de negócios; o administrador da API autoriza a API para o aplicativo de cada grupo; os membros de um grupo compartilham as credenciais do aplicativo do seu grupo.

Vantagem: Granularidade de gerenciamento moderada que distingue as origens de negócio sem sobrecarga excessiva. Desvantagem: Não é possível diferenciar ainda mais os membros dentro do mesmo grupo.

Recomendações para seleção de cenário

Três tipos de credenciais: Evite confusões

O Data Service utiliza três tipos distintos de credenciais de autenticação com finalidades, origens e cenários de uso diferentes. Certifique-se de distingui-las:

Resumo rápido: AccessKey serve para "conectar-se a fontes de dados", AppKey serve para "chamar APIs" e RAM serve para "acessar o console". Cada um tem uma finalidade diferente e não pode substituir os outros.

Confusão 1: "Minha chamada de API retorna 403, mas tenho permissões de administrador RAM" — As permissões RAM controlam as operações no console do DataWorks, não as permissões de chamada de API. As permissões de chamada são controladas pela autorização do aplicativo. Mesmo sendo um administrador RAM, você ainda precisa do AppKey/AppSecret de um aplicativo autorizado para chamar uma API.

Confusão 2: "O AccessKey configurado para a fonte de dados é o mesmo AppKey usado para chamadas de API?" — Não. O AccessKey é usado pelo Data Service para se conectar a fontes de dados de backend; o AppKey é usado pelos chamadores para invocar APIs. Eles são completamente independentes.

Confusão 3: O que devo inserir no campo "Alibaba Cloud Account ID" na página de autorização? — A página de autorização exige o ID da conta Alibaba Cloud (um valor numérico), não um nome de usuário RAM ou e-mail de login. Para obtê-lo, faça login na página Account Management e visualize o ID da conta nas configurações de segurança.

Comparação de métodos de autenticação

O API Gateway suporta dois métodos de autenticação. O Data Service adiciona "Autenticação APP Alibaba Cloud" às APIs do workspace por padrão. Escolha um método com base nos seus requisitos de segurança.

Autenticação simples (AppCode)

Adicione o AppCode ao cabeçalho da solicitação HTTP para concluir a autenticação. Nenhum cálculo de assinatura é necessário.

Exemplo de solicitação:

GET /api/v1/users?name=test HTTP/1.1
Host: your-api-endpoint.cn-shanghai.alicloudapi.com
Authorization: APPCODE 3f963a8e1cd7492bbd8a5e2e5e4c****

Autenticação por assinatura (AppKey + AppSecret)

O chamador usa o AppSecret para calcular uma assinatura HMAC-SHA256 sobre o conteúdo da solicitação e adiciona o AppKey e a assinatura ao cabeçalho da solicitação. O API Gateway recalcula a assinatura usando o mesmo AppSecret e a compara para verificar a identidade do chamador.

Exemplo de solicitação (seção de cabeçalho):

X-Ca-Key: 12345678
X-Ca-Signature: BASE64_ENCODED_SIGNATURE
X-Ca-Timestamp: 1741593600000
X-Ca-Nonce: unique-uuid-string
X-Ca-Signature-Headers: X-Ca-Key,X-Ca-Nonce,X-Ca-Timestamp

Comparação dos dois métodos

Recomendações de seleção:

• Fase de desenvolvimento e testes: Use AppCode para verificação rápida da API e redução de custos de desenvolvimento.

• Ambiente de produção: Sempre utilize autenticação por assinatura com AppKey + AppSecret e criptografia de transporte HTTPS.

• APIs expostas externamente: Uso obrigatório de autenticação por assinatura para evitar ataques de replay após interceptação de credenciais durante a transmissão.

Detalhes do algoritmo de assinatura

A autenticação por assinatura baseia-se no algoritmo HMAC-SHA256. O processo principal é descrito a seguir:

Visão geral do processo de assinatura

1. Construir a string de solicitação canônica (StringToSign): Concatene sequencialmente o método HTTP (GET/POST), cabeçalho Accept, Content-MD5 (valor MD5 do corpo da solicitação), Content-Type, Date, cabeçalhos personalizados envolvidos na assinatura (X-Ca-*, ordenados alfabeticamente) e a URL canônica (caminho + parâmetros de consulta ordenados).

2. Calcular a assinatura usando HMAC-SHA256: Assinatura = Base64(HMAC-SHA256(AppSecret, StringToSign))

3. Adicionar as informações de assinatura ao cabeçalho da solicitação: Inclui X-Ca-Key (AppKey), X-Ca-Signature (valor da assinatura), X-Ca-Timestamp (timestamp em milissegundos), X-Ca-Nonce (UUID para anti-replay) e X-Ca-Signature-Headers (lista de cabeçalhos envolvidos na assinatura).

Considerações importantes

Os detalhes a seguir são fontes comuns de erros de assinatura:

• Ordenação de parâmetros: Parâmetros de consulta da URL e cabeçalhos de assinatura devem ser ordenados por chave em ordem alfabética (ordem ASCII).

• Codificação de URL: Caracteres especiais nos valores dos parâmetros (espaços, caracteres chineses, etc.) devem ser codificados em URL.

• Separador de linha: As linhas em StringToSign devem ser separadas por \n (LF). Não use \r\n (CRLF).

• Tratamento de valores vazios: Quando não houver corpo, Content-MD5 é uma string vazia (não nula). Quando cabeçalhos como Accept não existirem, use também uma string vazia.

• Precisão do timestamp: X-Ca-Timestamp é um timestamp em nível de milissegundos. A diferença de tempo entre o cliente e o servidor não deve exceder 15 minutos.

• Unicidade do Nonce: Um UUID único deve ser gerado para cada solicitação como X-Ca-Nonce. Reutilizar um nonce aciona o bloqueio por ataque de replay.

Para exemplos completos de código em Java e Python, regras detalhadas de concatenação de StringToSign e métodos de depuração para erros comuns de assinatura, consulte a seção Algoritmo de assinatura na documentação do API Gateway.

Visualizar credenciais de autenticação

Após criar um aplicativo e obter autorização, recupere o AppKey, AppSecret ou AppCode para fazer chamadas de API.

Visualizar credenciais no console do Data Service

1. Faça login 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 Data Service, clique em Service Management na barra de menu superior.

3. No painel de navegação à esquerda, clique em Call APIs.

4. Na página Call APIs, visualize e copie as seguintes informações de autenticação: AppKey (identificador único do aplicativo), AppSecret (usado para autenticação por assinatura; mantenha-o seguro) e AppCode (usado para autenticação simples).

Visualizar credenciais no console do API Gateway: Faça login no console do API Gateway, localize o aplicativo de destino em Application Management e acesse a página de detalhes do aplicativo para visualizar o AppKey, AppSecret e AppCode.

AppSecret e AppCode são informações sensíveis. Não as exponha em repositórios de código, logs, páginas de frontend ou outros locais públicos. Se suspeitar de vazamento de credenciais, redefina imediatamente o AppSecret no console do API Gateway.

Chamar APIs usando o SDK do API Gateway

O API Gateway fornece SDKs para as principais linguagens de programação com implementações integradas do algoritmo de assinatura. Você só precisa fornecer o AppKey e o AppSecret. Para mais informações, consulte Chamar uma API e Download e uso do SDK.

Linguagens de SDK suportadas

Vantagens de usar o SDK

Em comparação à construção manual de solicitações HTTP, o SDK oferece estas vantagens:

• Assinatura automática: O SDK implementa o algoritmo de assinatura HMAC-SHA256, eliminando a necessidade de os desenvolvedores lidarem com detalhes de assinatura.

• Tentativa automática: Alguns SDKs incluem mecanismos integrados de nova tentativa para exceções de rede.

• Validação de parâmetros: O SDK valida os parâmetros antes de enviar as solicitações.

• Otimização de desempenho: Os SDKs geralmente usam pooling de conexões e HTTP/2 para melhorar o desempenho da rede.

Exemplo rápido de integração (Java)

O exemplo a seguir mostra como chamar uma API do Data Service usando o SDK Java do API Gateway:

// 1. Add Maven dependency // <dependency> // <groupId>com.aliyun.api.gateway</groupId> // <artifactId>sdk-core-java</artifactId> // <version>latest version</version> // </dependency> // 2. Initialize the client HttpClientBuilderParams params = new HttpClientBuilderParams(); params.setAppKey("your_app_key"); params.setAppSecret("your_app_secret"); ApacheHttpClient client = new ApacheHttpClient(params); // 3. Construct the request IoTApiRequest request = new IoTApiRequest(); request.setDomain("your-api-endpoint.cn-shanghai.alicloudapi.com"); request.setPath("/api/v1/query"); request.setHttpMethod("GET"); request.putQueryParam("pageSize", "10"); request.putQueryParam("pageNum", "1"); // 4. Execute the call ApiResponse response = client.execute(request); System.out.println("Response: " + response.getBody());

Exemplo rápido de integração (Python)

1. Install the SDK # pip install aliyun-api-gateway-sdk # 2. Call the API from com.alibaba.cloudapi.sdk.client import DefaultClient from com.alibaba.cloudapi.sdk.model import HttpClientBuilderParams params = HttpClientBuilderParams() params.app_key = "your_app_key" params.app_secret = "your_app_secret" params.host = "your-api-endpoint.cn-shanghai.alicloudapi.com" client = DefaultClient(params) response = client.get( path="/api/v1/query", query_params={"pageSize": "10", "pageNum": "1"}, headers={"Accept": "application/json"} ) print(f"Status: {response.status_code}") print(f"Body: {response.content}")

Para instruções detalhadas de uso, referências de API e códigos de exemplo para cada linguagem de SDK, consulte a seção Download e uso do SDK na documentação do API Gateway.

Resumo completo do processo de chamada

Processo completo desde a publicação da API até uma chamada bem-sucedida: O desenvolvedor da API desenvolve, testa e publica a API no API Gateway, que cria automaticamente um aplicativo padrão e a autorização. Para compartilhamento entre contas, o desenvolvedor autoriza manualmente a conta de destino. O chamador da API cria um aplicativo ou usa o aplicativo padrão, obtém credenciais (AppKey/AppSecret/AppCode), escolhe um método de autenticação (AppCode para autenticação simples ou AppKey + AppSecret para autenticação por assinatura) e chama a API através do SDK ou HTTP. Após o API Gateway verificar a identidade, o Data Service executa a consulta e retorna os resultados.

Referências

• Publicar uma API: Saiba como publicar uma API no API Gateway.

• Autorizar uma API: Saiba sobre operações de autorização e gerenciamento de APIs autorizadas para terceiros.

• Testar uma API: Teste APIs publicadas ou autorizadas na página Service Management.