Gerenciar as chaves de API

Esta página descreve como criar, editar e restringir chaves de API. Para informações sobre como usar chaves de API para acessar APIs do Google, consulte Usar chaves de API para acessar APIs.

Introdução às chaves de API

Há dois tipos de chaves de API: padrão e de autorização. As duas chaves permitem associar uma solicitação a um projeto para fins de faturamento e cota. No entanto, eles diferem da seguinte maneira:

  • Uma chave de API padrão não autentica um principal.

  • Uma chave de autorização faz a autenticação como uma conta de serviço. Ele opera de maneira semelhante a um token de acesso de longa duração.

A página Credenciais no consoleGoogle Cloud garante que o tipo correto de chave de API seja criado para uma API selecionada.

Chaves de API padrão

As chaves de API padrão oferecem uma maneira de associar uma solicitação a um projeto para fins de faturamento e cota. Quando você usa uma chave de API padrão (que não foi vinculada a uma conta de serviço) para acessar uma API, ela não identifica um principal. Sem um principal, a solicitação não pode usar o Identity and Access Management (IAM) para verificar se o autor da chamada está autorizado a realizar a operação solicitada.

As chaves de API padrão podem ser usadas com qualquer API que as aceite, a menos que restrições de API tenham sido adicionadas à chave. As chaves de API padrão não podem ser usadas com serviços que não as aceitam, incluindo no modo expresso.

Chaves de autorização

As chaves de autorização são chaves de API vinculadas a uma conta de serviço. Quando você usa uma chave de autorização para acessar uma API, sua solicitação é processada como se você tivesse usado a conta de serviço vinculada para fazer a solicitação.

As APIs que aceitam chaves de autorização incluem a AI Platform (aiplatform.googleapis.com) e a API Gemini (generativelanguage.googleapis.com).

Ao usar chaves de autorização, lembre-se do seguinte:

Componentes da chave de API

Uma chave de API tem os seguintes componentes, que permitem gerenciar e usar a chave:

String
A string da chave de API é uma string criptografada. Por exemplo, AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Ao usar uma chave de API para acessar uma API, você sempre usa a string da chave. As chaves de API não têm um arquivo JSON associado.
ID
O ID da chave de API é usado pelas ferramentas administrativas do Google Cloud para identificar a chave de forma exclusiva. O ID da chave não pode ser usado para acessar APIs. O ID da chave pode ser encontrado no URL da página de edição da chave no console do Google Cloud . Também é possível receber o ID da chave usando a Google Cloud CLI para listar as chaves no seu projeto.
Nome de exibição
O nome de exibição é um nome opcional e descritivo para a chave. É possível definir esse campo ao criar ou atualizar a chave.
Conta de serviço vinculada
As chaves de autorização incluem o endereço de e-mail da conta de serviço.

Antes de começar

Conclua as tarefas a seguir para usar as amostras nesta página.

Configurar a autenticação

Selecione a guia para como planeja usar as amostras nesta página:

Console

Quando você usa o console Google Cloud para acessar serviços Google Cloud e APIs, não é necessário configurar a autenticação.

gcloud

No console do Google Cloud , ative o Cloud Shell.

Ativar o Cloud Shell

Na parte de baixo do console Google Cloud , uma sessão do Cloud Shell é iniciada e exibe um prompt de linha de comando. O Cloud Shell é um ambiente shell com a CLI do Google Cloud já instalada e com valores já definidos para o projeto atual. A inicialização da sessão pode levar alguns segundos.

C++

Para usar os exemplos de C++ nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

Java

Para usar os exemplos em Java desta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

Python

Para usar os exemplos do Python nesta página em um ambiente de desenvolvimento local, instale e inicialize a CLI gcloud e configure o Application Default Credentials com suas credenciais de usuário.

  1. Instale a CLI do Google Cloud.

  2. Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

  3. Se você estiver usando um shell local, crie credenciais de autenticação local para sua conta de usuário: 

    gcloud auth application-default login

    Não é necessário fazer isso se você estiver usando o Cloud Shell.

    Se um erro de autenticação for retornado e você estiver usando um provedor de identidade (IdP) externo, confirme se você fez login na CLI gcloud com sua identidade federada.

Para mais informações, consulte Configurar o ADC para um ambiente de desenvolvimento local na documentação de autenticação do Google Cloud .

REST

Para usar as amostras da API REST nesta página em um ambiente de desenvolvimento local, use as credenciais fornecidas para a CLI gcloud.

    Instale a CLI do Google Cloud.

    Ao usar um provedor de identidade (IdP) externo, primeiro faça login na CLI gcloud com sua identidade federada.

Saiba mais em Autenticar para usar REST na documentação de autenticação do Google Cloud .

Funções exigidas

Para receber as permissões necessárias para gerenciar chaves de API, peça ao administrador para conceder a você os seguintes papéis do IAM no projeto:

Para mais informações sobre a concessão de papéis, consulte Gerenciar o acesso a projetos, pastas e organizações.

Também é possível conseguir as permissões necessárias usando papéis personalizados ou outros papéis predefinidos.

Ativar chaves de autorização

Antes de criar uma chave de autorização, faça uma das seguintes ações:

  • Atualize a restrição da política da organização constraints/iam.managed.disableServiceAccountApiKeyCreation para restringir os serviços em que os usuários podem criar chaves de autorização. Ao criar uma chave de autorização, os usuários precisam adicionar uma restrição de API que corresponda a um serviço permitido pela restrição.

  • Desative a restrição de política da organização constraints/iam.managed.disableServiceAccountApiKeyCreation.

Para mudar a política da organização, é necessário um recurso da organização. Não há suporte para projetos sem uma organização.

Para mudar a restrição de política, siga estas instruções.

Console

  1. No console do Google Cloud , acesse a página Políticas da organização.

    Acessar a página Políticas da organização

  2. Mude para a organização, pasta ou projeto em que você quer alterar as políticas.

  3. Na caixa Filtro, insira Block service e clique no nome da política Bloquear vinculações de chaves de API conta de serviço serviço.

  4. Clique em Gerenciar política.

  5. Na seção Origem da política, selecione Substituir política principal.

  6. Clique em Adicionar regra.

  7. Para desativar a restrição, defina Aplicação como Desativada.

    Para adicionar um serviço à lista de permissões, defina Aplicação como Ativada.

    1. Clique em Editar.

    2. Na seção Tipo de valor, selecione Definido pelo usuário.

    3. Insira o serviço para o qual você quer permitir a criação de chaves de API.

  8. Clique em Concluído.

  9. Opcional: clique em Testar alterações para ter insights sobre como a política proposta pode causar violações ou interrupções de compliance.

  10. Clique em Definir política.

gcloud

Para adicionar um serviço à lista de permissões, faça o seguinte:

  1. Crie um arquivo chamado spec.yaml com o conteúdo a seguir:

    name: SCOPE/SCOPE_ID/policies/iam.managed.disableServiceAccountApiKeyCreation
spec:
  rules:
  - enforce: true
    parameters:
      allowedServices:
      - SERVICE_NAME

    Forneça os valores a seguir:

    • SCOPE: organizations, folders ou projects.

    • SCOPE_ID: dependendo de SCOPE, o ID da organização, pasta ou projeto a que a política da organização se aplica.

    • SERVICE_NAME: o nome do serviço que você quer permitir. Por exemplo, compute.googleapis.com.

  2. Execute o comando gcloud a seguir para permitir a vinculação de chaves de API a contas de serviço para o serviço especificado:

    gcloud org-policies set-policy spec.yaml \
    --update-mask spec

Para desativar a restrição, faça o seguinte:

  1. Crie um arquivo chamado spec.yaml com o conteúdo a seguir:

    name: SCOPE/SCOPE_ID/policies/iam.managed.disableServiceAccountApiKeyCreation
spec:
  rules:
  - enforce: false

  2. Execute o seguinte comando gcloud para desativar a restrição:

    gcloud org-policies set-policy spec.yaml \
    --update-mask spec

Criar uma chave de API

Para criar uma chave de API, use uma das seguintes opções:

Console

  1. No console Google Cloud , acesse a página Credenciais:

    Ir para Credenciais

  2. Clique em Criar credenciais e selecione Chave de API no menu.

  3. Adicione pelo menos uma restrição de chave de API. Para mais informações, consulte Aplicar restrições de chave de API.

  4. Opcional: para vincular a chave de API a uma conta de serviço e criar uma chave de autorização, marque a caixa de seleção Autenticar chamadas de API por uma conta de serviço e clique em Selecionar uma conta de serviço para escolher a conta que você quer vincular à chave.

    Para mais informações, consulte Chaves de autorização.

  5. Clique em Criar. A caixa de diálogo Chave de API criada mostra a string da chave recém-criada.

gcloud

Use o comando gcloud services api-keys create para criar uma chave de API.

 gcloud services api-keys create \
     --display-name=DISPLAY_NAME \
     --api-target=service=SERVICE_1 \
     --api-target=service=SERVICE_2

Substitua os seguintes valores:

  • DISPLAY_NAME: um nome descritivo para a chave.

  • SERVICE_1, SERVICE_2...: os nomes de serviço das APIs que poderão usar a chave para serem acessadas.

    Para encontrar o nome do serviço, pesquise a API no Painel de APIs. Os nomes de serviço são strings como