Além do console web, o Key Management Service (KMS) oferece diversos métodos de integração programática, incluindo depuração online da OpenAPI, Alibaba Cloud SDK e Terraform, para ajudar você a desenvolver e implantar suas aplicações com mais eficiência.
Processo de integração
Descrição da versão
Você pode depurar online a lista de APIs da versão 2016-01-20. A string 2016-01-20 representa o número da versão da API, não uma data. Os dados exibidos correspondem às informações públicas mais recentes da API, que continua recebendo atualizações desde 2016-01-20. Para saber como visualizar a versão da API, consulte Visualize API versions.
Versão | Descrição |
Recomendada |
Depuração online
Para ajudar os desenvolvedores a aprender e usar a OpenAPI da Alibaba Cloud de forma rápida e eficiente, a Alibaba Cloud disponibiliza o portal OpenAPI. Esse portal integra pesquisa inteligente de OpenAPI, documentação, depuração online, downloads de SDK, exemplos de código, diagnóstico de erros e estatísticas de chamadas. Com ele, você chama as OpenAPIs dos serviços da Alibaba Cloud e visualiza os resultados das requisições e respostas. O portal também gera automaticamente exemplos de código do SDK para acelerar o uso dos serviços da Alibaba Cloud. Para mais informações, consulte What is OpenAPI?.
O KMS suporta a depuração de API no portal OpenAPI da Alibaba Cloud. Antes de começar, familiarize-se com a versão da API, os endpoints e os parâmetros da API. Após fazer login no portal OpenAPI com sua conta Alibaba Cloud, o sistema utiliza essa conta por padrão para a depuração online da OpenAPI.
O ponto de entrada para depuração da API é: https://next.api.alibabacloud.com/api/Kms/2016-01-20
Após o login no portal OpenAPI, o painel à esquerda exibe a lista de APIs do KMS (como DescribeRegions). A área central serve para definir os parâmetros de entrada da API e clicar em Send Request. O painel direito mostra informações como Documentation, Debugging Result, SDK Sample Code e CLI Sample Code, além das definições dos parâmetros de resposta.
Endpoints
O KMS oferece dois tipos de gateway: compartilhado e dedicado. Gateways compartilhados atendem tanto a operações do plano de controle quanto do plano de dados, enquanto gateways dedicados são exclusivos para operações do plano de dados. O acesso aos gateways compartilhados ocorre pela internet ou por uma VPC; já os gateways dedicados utilizam a rede privada do KMS. Cada tipo possui endpoints distintos. Para entender melhor as diferenças entre eles, consulte Alibaba Cloud SDK.
Endpoint do gateway compartilhado (também conhecido como endpoint de service do KMS)
Para chamar operações criptográficas do plano de dados por meio de um gateway compartilhado, ative primeiro o acesso à rede pública. Para mais informações, consulte Access keys in a KMS instance over the public network.
Escolha o endpoint de service conforme a região onde seus recursos estão localizados para reduzir a latência. Por exemplo, na região China (Hangzhou), o endpoint público do KMS é kms.cn-hangzhou.aliyuncs.com, e o endpoint de VPC é kms-vpc.cn-hangzhou.aliyuncs.com. Para obter a lista completa de endpoints, consulte Endpoints.
Os endpoints públicos permitem acesso global.
-
Os endpoints de VPC só aceitam conexões originadas dentro da respectiva região da Alibaba Cloud e exclusivamente via rede VPC. Principais vantagens desses endpoints:
Segurança reforçada: como o acesso se restringe ao interior da VPC, há maior proteção e privacidade.
Resposta mais rápida: por operarem na rede interna da VPC, esses endpoints geralmente entregam tempos de resposta menores e evitam problemas típicos da rede pública, como latência elevada e limites de largura de banda.
Custo reduzido: a comunicação ocorre inteiramente pela rede interna.
Endpoint do gateway dedicado (também conhecido como endpoint de instância do KMS)
O gateway dedicado é acessível apenas pela rede privada do KMS. Seu formato de endpoint segue o padrão <YOUR_KMS_INSTANCE_ID>.cryptoservice.kms.aliyuncs.com, por exemplo, kst-hzz65f176a0ogplgq****.cryptoservice.kms.aliyuncs.com.
Substitua
<YOUR_KMS_INSTANCE_ID>pelo ID da instância do KMS que você está utilizando.Ao chamar operações do plano de dados por um gateway dedicado, adicione a configuração do certificado CA da instância durante a inicialização do cliente. Para mais detalhes, consulte Initialize the client.
Métodos de autenticação
Os métodos de autenticação são idênticos tanto para gateways compartilhados quanto dedicados ao acessar a OpenAPI via Alibaba Cloud SDK. O KMS aceita mecanismos de autenticação baseados em RAM, como AccessKey, token STS, RamRoleArn e função RAM de instância ECS. Para mais informações, consulte Gerencie credentials e Identity, credentials, and authorization. Para orientações sobre como configurar políticas de acesso, veja Use RAM to implement access control.
AccessKey
Por padrão, uma conta Alibaba Cloud possui permissões de administrador sobre todos os recursos, e isso não pode ser alterado. Para garantir a segurança dos recursos, recomendamos criar um par de AccessKey usando um usuário RAM e conceder apenas as permissões estritamente necessárias.
Faça login no console do RAM. Na página Users, clique em no nome do usuário RAM desejado.
Na aba Secret Management, dentro da seção AccessKey, clique em em Create AccessKey.
-
Conceda ao usuário RAM as permissões necessárias para acessar o KMS.
-
Opção 1: Configure uma política baseada em identidade
Na coluna Actions do usuário RAM, clique em em Grant Permission para vincular uma política de permissão de sistema pré-definida do KMS ao usuário. Para conhecer as políticas de sistema disponíveis para o KMS, consulte System policies for KMS.
NotaTambém é possível crie políticas de permissão personalizadas. Saiba mais em Crie a custom policy.
-
Opção 2: Configure uma política baseada em recurso
O KMS aceita políticas baseadas em recurso que concedem permissões de acesso a chaves e segredos individuais. Essas políticas permitem controlar quais contas Alibaba Cloud, usuários RAM e funções RAM podem gerencie ou utilizar chaves e segredos do KMS. Para mais detalhes, consulte Key policies e Secret policies.
-
Função RAM do ECS
Uma função RAM de instância ECS permite obter uma credencial de acesso temporária (token STS) diretamente de dentro de uma instância ECS para chamar operações da API do KMS, eliminando a necessidade de configure um par de AccessKey.
Para mais informações, consulte Instance RAM roles.
-
Acesse o console do RAM e crie uma função RAM confiável para um service da Alibaba Cloud.
Tipo de entidade confiável: selecione Elastic Compute Service.
Entidade confiável: escolha Elastic Compute Service (ECS).
-
Conceda à função RAM as permissões necessárias para acessar o KMS.
-
Opção 1: Configure uma política baseada em identidade
Na coluna Actions da função RAM, clique em em Grant Permission para vincular uma política de permissão de sistema pré-definida do KMS à função. Para conhecer as políticas de sistema disponíveis para o KMS, consulte System policies for KMS.
NotaTambém é possível crie políticas de permissão personalizadas. Saiba mais em Crie a custom policy.
-
Opção 2: Configure uma política baseada em recurso
O KMS aceita políticas baseadas em recurso que concedem permissões de acesso a chaves e segredos individuais. Essas políticas permitem controlar quais contas Alibaba Cloud, usuários RAM e funções RAM podem gerencie ou utilizar chaves e segredos do KMS. Para mais detalhes, consulte Key policies e Secret policies.
-
Faça login no console do ECS e anexe a função RAM a uma instância ECS.
Token STS
O Security Token Service (STS) emite uma credencial de acesso temporária, chamada token STS, para um usuário ou função RAM. Esse token concede acesso ao KMS com permissões específicas durante um período limitado de validade. Após expirar, ele se torna inválido automaticamente.
Acesse o console do RAM para crie um usuário ou uma função RAM. Para mais informações, consulte Crie a RAM user e Crie a RAM role.
Conceda a permissão
AliyunSTSAssumeRoleAccessao usuário ou função RAM. Consulte Gerencie RAM user permissions e Grant permissions to a RAM role para detalhes.-
Conceda ao usuário ou função RAM as permissões necessárias para acessar o KMS.
-
Opção 1: Configure uma política baseada em identidade
Na coluna Actions da função ou usuário RAM, clique em em Grant Permission para vincular uma política de permissão de sistema pré-definida do KMS. Para conhecer as políticas de sistema disponíveis para o KMS, consulte System policies for KMS.
NotaTambém é possível crie políticas de permissão personalizadas. Saiba mais em Crie a custom policy.
-
Opção 2: Configure uma política baseada em recurso
O KMS aceita políticas baseadas em recurso que concedem permissões de acesso a chaves e segredos individuais. Essas políticas permitem controlar quais contas Alibaba Cloud, usuários RAM e funções RAM podem gerencie ou utilizar chaves e segredos do KMS. Para mais detalhes, consulte Key policies e Secret policies.
-
Utilize o usuário ou função RAM para chamar a operação STS AssumeRole e obter uma credencial de acesso STS temporária. Para mais informações, consulte AssumeRole.
RamRoleArn
Usuários RAM ou serviços cloud podem assumir uma função para obter permissões temporárias (token STS) em vez de usar chaves de longo prazo, o que reduz o risco de vazamento de chaves. Por exemplo, em uma tarefa temporária de processamento de dados, um usuário RAM ou service cloud assume momentaneamente uma função com um RamRoleArn específico. Ao concluir a tarefa, as permissões da função são revogadas, minimizando o risco de exposição.
-
Crie um par de AccessKey para o usuário
Faça login no console do RAM. No painel de navegação à esquerda, escolha . Na página Users, clique em no nome do usuário RAM desejado.
Anexe a política de sistema
AliyunSTSAssumeRoleAccessou uma política personalizada que inclua a açãosts:AssumeRoleao usuário RAM.Na aba Secret Management, dentro da seção AccessKey, clique em em Create AccessKey.
-
Crie e autorize uma função RAM:
No painel de navegação à esquerda, escolha . Na página Roles, clique em em Create Role. Para mais informações, consulte Crie a RAM role.
-
Conceda à função RAM as permissões necessárias para acessar o KMS.
-
Opção 1: Configure uma política baseada em identidade
Na coluna Actions da função RAM, clique em em Grant Permission para vincular uma política de permissão de sistema pré-definida do KMS à função. Para conhecer as políticas de sistema disponíveis para o KMS, consulte System policies for KMS.
NotaTambém é possível crie políticas de permissão personalizadas. Saiba mais em Crie a custom policy.
-
Opção 2: Configure uma política baseada em recurso
O KMS aceita políticas baseadas em recurso que concedem permissões de acesso a chaves e segredos individuais. Essas políticas permitem controlar quais contas Alibaba Cloud, usuários RAM e funções RAM podem gerencie ou utilizar chaves e segredos do KMS. Para mais detalhes, consulte Key policies e Secret policies.
-
-
Obtenha o RamRoleArn da função RAM desejada. Para mais informações, consulte Visualize the information about a RAM role.
No painel de navegação à esquerda, escolha . Na página Roles, clique em no nome da função desejada.
-
Na página de detalhes da função, localize o RamRoleArn na seção ARN.
NotaO RamRoleArn corresponde ao Alibaba Cloud Resource Name (ARN) da função RAM a ser assumida. O formato é
acs:ram::$accountID:role/$roleName, onde$accountIDé o ID da conta Alibaba Cloud e$roleNameé o nome da função RAM.
Métodos de integração
O SDK é a maneira mais simples e com melhor suporte para chamar a OpenAPI. Recomendamos seu uso.
Alibaba Cloud SDK
A Alibaba Cloud oferece SDKs para diversas linguagens de programação (Java, C#, Go, Python, Node.js/TypeScript, PHP, C++, entre outras). Esses SDKs encapsulam a lógica de assinatura, o mecanismo de timeout e o mecanismo de retry, além de fornecer objetos de requisição e resposta para chamadas de API, simplificando o desenvolvimento. Para mais informações sobre o Alibaba Cloud SDK, consulte Alibaba Cloud SDK.
Alibaba Cloud CLI
O Alibaba Cloud CLI (Alibaba Cloud Command Line Interface) é uma ferramenta unificada de linha de comando construída sobre a OpenAPI da Alibaba Cloud. Com ela, você interage com os serviços da Alibaba Cloud e gerencie seus recursos diretamente pelo shell, executando comandos sem depender de uma interface gráfica (GUI). Para mais informações, consulte What is Alibaba Cloud CLI. Para saber como obter e usar os comandos do Alibaba Cloud CLI, veja Get started with Alibaba Cloud CLI.
Terraform
O Terraform é uma ferramenta open source que permite visualizar, provisionar e gerencie infraestrutura e recursos cloud de forma segura e eficiente. Ele converte modelos em uma estrutura de dados interna antes de chamar a OpenAPI e suporta os principais provedores de cloud do mercado. O Terraform calcula automaticamente as diferenças entre recursos e gera um plano de execução, permitindo visualizar o impacto das alterações antes de aplicá-las — o que ajuda a evitar danos acidentais a recursos ou interrupções de service. Para mais informações, consulte What is Alibaba Cloud Terraform?. Para começar rapidamente a orquestrar o Key Management Service com Terraform, veja Overview.
Apenas algumas operações da API do KMS são suportadas ao usar o Terraform para orquestrar e utilizar o Key Management Service.
Encapsulamento personalizado de chamadas de API
Chamadas HTTP nativas exigem que você implemente o algoritmo de assinatura por conta própria, construa requisições personalizadas com base nos parâmetros da API e inicie as chamadas HTTP. Para detalhes sobre o algoritmo de assinatura, consulte Signature mechanism. Além dos parâmetros de negócio obrigatórios, é necessário concatenar os parâmetros comuns da requisição. Para mais informações, consulte Common parameters. Para ver um exemplo de chamada de API personalizada, consulte Request syntax and signature method V3.
Observações de uso
O KMS aceita requisições exclusivamente via HTTPS. As versões TLS 1.0, 1.1 e 1.2 são suportadas. SSL v2 e SSL v3 não são suportados.
-
O limite máximo de consultas por segundo (QPS) de uma única conta Alibaba Cloud varia conforme a API. Consulte o limite de QPS na documentação de cada API para obter detalhes. Para mais informações, veja Throttling and quota management.
NotaTodos os usuários RAM vinculados a uma mesma conta Alibaba Cloud compartilham a cota de QPS dessa conta.
Caso uma chamada de API retorne erro, verifique se os parâmetros da requisição e seus valores estão corretos com base no código de erro retornado. Para mais informações, consulte Common error codes.
Registre o RequestID retornado pela chamada de API ou a mensagem de erro do SDK e utilize o Diagnóstico da OpenAPI da Alibaba Cloud para realizar diagnósticos de autoatendimento.