Autenticar usando chaves de API

Nesta página, descrevemos como usar chaves de API para autenticar APIs e serviços do Google Cloud compatíveis com chaves de API.

A maioria das APIs do Google Cloud não são compatíveis com chaves de API. Verifique se a API que você quer usar é compatível com chaves de API antes de usar esse método de autenticação.

Para informações sobre o uso de chaves de API para autenticação na Plataforma Google Maps, consulte a documentação da Plataforma Google Maps. Para mais informações sobre a API de chaves de API, consulte a documentação da API de chaves de API.

Introdução às chaves de API

Quando você usa uma chave de API para autenticar uma API, ela não identifica um principal nem fornece informações de autorização. Portanto, a solicitação não usa o Identity and Access Management (IAM) para verificar se o autor da chamada tem permissão para executar a operação solicitada.

A chave de API associa a solicitação a um projeto do Google Cloud para fins de faturamento e cota. Como as chaves de API não identificam o autor da chamada, elas geralmente são usadas para acessar dados ou recursos públicos.

Muitas APIs do Google Cloud não aceitam chaves de API para autenticação. Leia a documentação de autenticação do serviço ou da API que você quer usar para determinar se é compatível com chaves de API.

Uma chave de API tem os seguintes componentes, que você usa para 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 autenticar, você sempre usará 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 autenticação. 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.

Para gerenciar chaves de API, é necessário ter o papel Administrador de chaves de API (roles/serviceusage.apiKeysAdmin) no projeto.

Antes de começar

Select the tab for how you plan to use the samples on this page:

Console

When you use the Google Cloud console to access Google Cloud services and APIs, you don't need to set up authentication.

gcloud

In the Google Cloud console, activate Cloud Shell.

Activate Cloud Shell

At the bottom of the Google Cloud console, a Cloud Shell session starts and displays a command-line prompt. Cloud Shell is a shell environment with the Google Cloud CLI already installed and with values already set for your current project. It can take a few seconds for the session to initialize.

Java

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

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

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

Python

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

  1. Install the Google Cloud CLI.

  2. To initialize the gcloud CLI, run the following command: 

    gcloud init

  3. If you're using a local shell, then create local authentication credentials for your user account: 

    gcloud auth application-default login

    You don't need to do this if you're using Cloud Shell.

Para mais informações, consulte Configurar a autenticação 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 gcloud CLI.

    Install the Google Cloud CLI, then initialize it by running the following command: 

    gcloud init

Para mais informações, consulte Autenticar para usar REST na documentação de autenticação do Google Cloud.

crie uma chave de API

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

Console

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

    Ir para Credenciais

  2. Clique em Criar credenciais e, em seguida, selecione a chave de API no menu.

    A caixa de diálogo Chave de API criada exibirá a string da chave recém-criada.

gcloud

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

Substitua DISPLAY_NAME por um nome descritivo para a chave.

 gcloud services api-keys create --display-name=DISPLAY_NAME

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.ApiTarget;
import com.google.api.apikeys.v2.CreateKeyRequest;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.LocationName;
import com.google.api.apikeys.v2.Restrictions;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class CreateApiKey {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    //  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  3. Make sure you have the necessary permission to create API keys.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    createApiKey(projectId);
  }

  // Creates an API key.
  public static void createApiKey(String projectId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      Key key = Key.newBuilder()
          .setDisplayName("My first API key")
          // Set the API key restriction.
          // You can also set browser/ server/ android/ ios based restrictions.
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys#api_key_restrictions
          .setRestrictions(Restrictions.newBuilder()
              // Restrict the API key usage by specifying the target service and methods.
              // The API key can only be used to authenticate the specified methods in the service.
              .addApiTargets(ApiTarget.newBuilder()
                  .setService("translate.googleapis.com")
                  .addMethods("translate.googleapis.com.TranslateText")
                  .build())
              .build())
          .build();

      // Initialize request and set arguments.
      CreateKeyRequest createKeyRequest = CreateKeyRequest.newBuilder()
          // API keys can only be global.
          .setParent(LocationName.of(projectId, "global").toString())
          .setKey(key)
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.createKeyAsync(createKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      // To restrict the usage of this API key, use the value in "result.getName()".
      System.out.printf("Successfully created an API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def create_api_key(project_id: str, suffix: str) -> Key:
    """
    Creates and restrict an API key. Add the suffix for uniqueness.

    TODO(Developer):
    1. Before running this sample,
      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    2. Make sure you have the necessary permission to create API keys.

    Args:
        project_id: Google Cloud project id.

    Returns:
        response: Returns the created API Key.
    """
    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    key = api_keys_v2.Key()
    key.display_name = f"My first API key - {suffix}"

    # Initialize request and set arguments.
    request = api_keys_v2.CreateKeyRequest()
    request.parent = f"projects/{project_id}/locations/global"
    request.key = key

    # Make the request and wait for the operation to complete.
    response = client.create_key(request=request).result()

    print(f"Successfully created an API key: {response.name}")
    # For authenticating with the API key, use the value in "response.key_string".
    # To restrict the usage of this API key, use the value in "response.name".
    return response

REST

Use o método keys.create para criar uma chave de API. Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para receber as informações da nova chave.

Substitua os seguintes valores:

  • DISPLAY_NAME: opcional. Um nome descritivo para a chave.
  • PROJECT_ID: o nome ou ID do projeto do Google Cloud.
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
-d {'"displayName" : "DISPLAY_NAME"'} \
"https://apikeys.googleapis.com/v2/projects/PROJECT/locations/global/keys"

Para mais informações sobre como criar chaves de API usando a API REST, consulte Como criar uma chave de API, na documentação de API de chaves de API.

Copie a string da chave e guarde-a com segurança. A menos que você esteja usando uma chave de teste que queira excluir mais tarde, adicione restrições de aplicativo e chave de API.

Usar uma chave de API

Se uma API for compatível com o uso de chaves de API, será possível usá-las para autenticar essa API. É possível usar chaves de API com solicitações REST e com bibliotecas de cliente compatíveis.

Usar uma chave de API com REST

É possível transmitir a chave de API para uma chamada da API REST como um parâmetro de consulta com o seguinte formato. Substitua API_KEY pela string da sua chave de API.

Por exemplo, para transmitir uma chave de API de uma solicitação da API Cloud Natural Language a documents.analyzeEntities:

POST https://language.googleapis.com/v1/documents:analyzeEntities?key=API_KEY

Como alternativa, é possível usar o cabeçalho x-goog-api-key para transmitir sua chave. Esse cabeçalho precisa ser usado com solicitações gRPC.

curl -X POST \
    -H "X-goog-api-key: API_KEY" \
    -H "Content-Type: application/json; charset=utf-8" \
    -d @request.json \
    "https://translation.googleapis.com/language/translate/v2"

Usar uma chave de API com bibliotecas de cliente

O suporte da biblioteca de cliente às chaves de API é específico da linguagem.

Este exemplo usa a API Cloud Natural Language, que oferece suporte a chaves de API para autenticação, e demonstra como fornecer uma chave de API à biblioteca.

Node.js

Para executar esta amostra, você precisa instalar a biblioteca de cliente do Natural Language e a biblioteca de cliente de chaves de API.


const {
  v1: {LanguageServiceClient},
} = require('@google-cloud/language');

/**
 * Authenticates with an API key for Google Language service.
 *
 * @param {string} apiKey An API Key to use
 */
async function authenticateWithAPIKey(apiKey) {
  const language = new LanguageServiceClient({apiKey});

  // Alternatively:
  // const auth = new GoogleAuth({apiKey});
  // const {GoogleAuth} = require('google-auth-library');
  // const language = new LanguageServiceClient({auth});

  const text = 'Hello, world!';

  const [response] = await language.analyzeSentiment({
    document: {
      content: text,
      type: 'PLAIN_TEXT',
    },
  });

  console.log(`Text: ${text}`);
  console.log(
    `Sentiment: ${response.documentSentiment.score}, ${response.documentSentiment.magnitude}`
  );
  console.log('Successfully authenticated using the API key');
}

authenticateWithAPIKey();

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente do Natural Language e a biblioteca de cliente de chaves de API.


from google.cloud import language_v1


def authenticate_with_api_key(api_key_string: str) -> None:
    """
    Authenticates with an API key for Google Language service.

    TODO(Developer): Replace this variable before running the sample.

    Args:
        api_key_string: The API key to authenticate to the service.
    """

    # Initialize the Language Service client and set the API key
    client = language_v1.LanguageServiceClient(
        client_options={"api_key": api_key_string}
    )

    text = "Hello, world!"
    document = language_v1.Document(
        content=text, type_=language_v1.Document.Type.PLAIN_TEXT
    )

    # Make a request to analyze the sentiment of the text.
    sentiment = client.analyze_sentiment(
        request={"document": document}
    ).document_sentiment

    print(f"Text: {text}")
    print(f"Sentiment: {sentiment.score}, {sentiment.magnitude}")
    print("Successfully authenticated using the API key")

Proteger uma chave de API

Ao usar chaves de API nos seus aplicativos, garanta que elas sejam mantidas em segurança durante o armazenamento e a transmissão. A exposição pública das chaves de API pode levar a cobranças inesperadas na sua conta. Para manter as chaves de API em segurança, siga estas práticas recomendadas:

  • Adicione restrições da chave de API à sua chave.

    Ao adicionar restrições, é possível limitar como uma chave de API pode ser usada, reduzindo o impacto de uma chave de API comprometida.

  • Exclua chaves de API desnecessárias para minimizar a exposição a ataques.

  • Recrie as chaves de API periodicamente.

    Crie periodicamente novas chaves de API, exclua as antigas e atualize os aplicativos para usar as novas chaves.

Aplicar restrições de chave API

As chaves de API são irrestritas por padrão. As chaves irrestritas não são seguras porque podem ser usadas por qualquer pessoa e de qualquer lugar. Para aplicativos de produção, defina as restrições de aplicativos e as restrições de API.

Adicionar restrições ao aplicativo

As restrições de aplicativo especificam quais sites, endereços IP ou apps podem usar uma chave de API.

Só é possível aplicar um tipo de restrição de aplicativo por vez. Escolha o tipo de restrição com base nas necessidades do aplicativo.

Opção Tipo de aplicativo Observações
Referenciadores HTTP Aplicativos da Web Especifica os sites que podem usar a chave.
Endereços IP Aplicativos chamados por servidores específicos Especifica os servidores ou cron jobs que podem usar a chave.
Apps Android Aplicativos Android Especifica o app Android que pode usar a chave.
Apps iOS Aplicativos iOS Especifica os pacotes do iOS que podem usar a chave.

Referenciadores HTTP

Para restringir os sites que podem usar a chave de API, adicione uma ou mais restrições de referenciadores de HTTP.

É possível substituir um caractere curinga (*) pelo subdomínio ou pelo caminho, mas não é possível inserir um caractere curinga no meio do URL. Por exemplo, *.example.com é válido e aceita todos os sites que terminam em .example.com. No entanto, mysubdomain*.example.com não é uma restrição válida.

Os números de porta podem ser incluídos em restrições de referenciadores de HTTP. Se você incluir um número de porta, apenas as solicitações que usam essa porta serão correspondidas. Se você não especificar um número de porta, as solicitações de qualquer número de porta serão correspondidas.

É possível adicionar até 1.200 referenciadores HTTP a uma chave de API.

A tabela a seguir mostra alguns exemplos de cenários e restrições do navegador:

Cenário Restrições
Permitir um URL específico Adicione um URL com um caminho exato. Por exemplo:
www.example.com/path
www.example.com/path/path

Alguns navegadores implementam uma política de referenciador que envia somente o URL de origem para solicitações entre origens. Os usuários desses navegadores não podem usar chaves com restrições de URL específicas da página.

Permitir qualquer URL no site É preciso definir dois URLs na lista allowedReferers.
  1. URL do domínio, sem um subdomínio e com um caractere curinga no caminho. Por exemplo:
    example.com/*
  2. Um segundo URL que inclui um caractere curinga para o subdomínio e um curinga para o caminho. Por exemplo:
    *.example.com/*
Permitir qualquer URL em um único subdomínio ou domínio sem "www".

É preciso definir dois URLs na lista allowedReferers para permitir um domínio inteiro:

  1. URL para o domínio, sem uma barra no final. Por exemplo:
    www.example.com
    sub.example.com
    example.com
  2. Um segundo URL para o domínio que inclui um caractere curinga no caminho. Por exemplo:
    www.example.com/*
    sub.example.com/*
    example.com/*

Para restringir sua chave de API a sites específicos, use uma das seguintes opções:

Console

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

    Ir para Credenciais

  2. Clique no nome da chave de API que você quer restringir.

  3. Na seção Restrições de aplicativo, selecione Referenciadores HTTP.

  4. Para cada restrição que você quiser adicionar, clique em Adicionar um item, insira a restrição e clique em Concluído.

  5. Clique em Salvar para salvar as mudanças e retornar à lista de chaves de API..

gcloud

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list para listar as chaves do projeto.

  2. Use o comando gcloud services api-keys update para adicionar restrições de referenciadores de HTTP a uma chave de API.

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restringir.

    • ALLOWED_REFERRER_1: a restrição do referenciador de HTTP.

      Você pode adicionar quantas restrições forem necessárias. use vírgulas para separar as restrições. É necessário fornecer todas as restrições do referenciador com o comando update. As restrições de referenciadores fornecidas substituem todas as restrições de referenciadores atuais na chave.

    gcloud services api-keys update KEY_ID \
 --allowed-referrers="ALLOWED_REFERRER_1"

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.BrowserKeyRestrictions;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyHttp {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyHttp(projectId, keyId);
  }

  // Restricts an API key. To restrict the websites that can use your API key,
  // you add one or more HTTP referrer restrictions.
  public static void restrictApiKeyHttp(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage to specific websites by adding them
      // to the list of allowed_referrers.
      Restrictions restrictions = Restrictions.newBuilder()
          .setBrowserKeyRestrictions(BrowserKeyRestrictions.newBuilder()
              .addAllowedReferrers("www.example.com/*")
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_http(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. To restrict the websites that can use your API key,
    you add one or more HTTP referrer restrictions.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage to specific websites by adding them to the list of allowed_referrers.
    browser_key_restrictions = api_keys_v2.BrowserKeyRestrictions()
    browser_key_restrictions.allowed_referrers = ["www.example.com/*"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.browser_key_restrictions = browser_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Você pode conseguir o ID usando o método keys.list. O ID é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"

  2. Use o método keys.patch para adicionar restrições de referenciadores de HTTP à chave de API.

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

    • ALLOWED_REFERRER_1: a restrição do referenciador de HTTP.

      Você pode adicionar quantas restrições forem necessárias. use vírgulas para separar as restrições. É necessário fornecer todas as restrições do referenciador com a solicitação. as restrições do referenciador fornecidas substituem todas as restrições de referenciador atuais na chave.

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

    • KEY_ID: o ID da chave que você quer restringir.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"restrictions" : {
"browserKeyRestrictions": {
  "allowedReferrers": ["ALLOWED_REFERRER_1"]
}
}
}' \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Para mais informações sobre como adicionar restrições de referenciadores de HTTP a uma chave usando a API REST, consulte Como adicionar restrições de navegador, na documentação de API de chaves de API.

Endereços IP

Especifique um ou mais endereços IP dos autores da chamada, como um servidor da Web ou um cron job, autorizados a usar a chave de API. É possível especificar os endereços IP em qualquer um dos seguintes formatos:

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • Uma sub-rede usando a notação CIDR (198.51.100.0/24, 2001:db8::/64)

O uso de localhost não é compatível com restrições de servidor.

Para restringir sua chave de API a endereços IP específicos, use uma das seguintes opções:

Console

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

    Ir para Credenciais

  2. Clique no nome da chave de API que você quer restringir.

  3. Na seção Restrições de aplicativo, selecione Endereços IP.

  4. Para cada endereço IP que você quiser adicionar, clique em Adicionar um item, insira o endereço e clique em Concluído.

  5. Clique em Salvar para salvar as mudanças e retornar à lista de chaves de API..

gcloud

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list para listar as chaves do projeto.

  2. Use o comando gcloud services api-keys update para adicionar restrições de servidor (endereço IP) a uma chave de API.

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restringir.

    • ALLOWED_IP_ADDR_1: seu endereço IP permitido.

      Você pode adicionar quantos endereços IP forem necessários. use vírgulas para separar os endereços.

    gcloud services api-keys update KEY_ID \
--allowed-ips="ALLOWED_IP_ADDR_1"

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.ServerKeyRestrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyServer {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyServer(projectId, keyId);
  }

  // Restricts the API key based on IP addresses. You can specify one or more IP addresses
  // of the callers, for example web servers or cron jobs, that are allowed to use your API key.
  public static void restrictApiKeyServer(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the IP addresses.
      // You can specify the IP addresses in IPv4 or IPv6 or a subnet using CIDR notation.
      Restrictions restrictions = Restrictions.newBuilder()
          .setServerKeyRestrictions(ServerKeyRestrictions.newBuilder()
              .addAllAllowedIps(Arrays.asList("198.51.100.0/24", "2000:db8::/64"))
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_server(project_id: str, key_id: str) -> Key:
    """
    Restricts the API key based on IP addresses. You can specify one or more IP addresses of the callers,
    for example web servers or cron jobs, that are allowed to use your API key.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the IP addresses.
    # You can specify the IP addresses in IPv4 or IPv6 or a subnet using CIDR notation.
    server_key_restrictions = api_keys_v2.ServerKeyRestrictions()
    server_key_restrictions.allowed_ips = ["198.51.100.0/24", "2000:db8::/64"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.server_key_restrictions = server_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Você pode conseguir o ID usando o método keys.list. O ID é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"

  2. Use o método keys.patch para adicionar restrições de servidor (endereço IP) a uma chave de API.

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

    • ALLOWED_IP_ADDR_1: seu endereço IP permitido.

      Você pode adicionar quantos endereços IP forem necessários. use vírgulas para separar as restrições. É preciso fornecer todos os endereços IP com a solicitação, as restrições do referenciador fornecidas substituem todas as restrições de endereços IP existentes na chave.

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

    • KEY_ID: o ID da chave que você quer restringir.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"restrictions" : {
  "serverKeyRestrictions": {
    "allowedIps": ["ALLOWED_IP_ADDR_1"]
  }
}
}' \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Para mais informações sobre como adicionar restrições de endereço IP a uma chave usando a API REST, consulte Como adicionar restrições de servidor, na documentação de API de chaves de API.

Apps Android

É possível restringir o uso de uma chave de API a apps Android específicos. Forneça o nome do pacote e a impressão digital do certificado SHA-1 de 20 bytes para cada app.

Ao usar a chave de API em uma solicitação, é preciso especificar o nome do pacote e a impressão digital do certificado usando os seguintes cabeçalhos HTTP:

  • X-Android-Package
  • X-Android-Cert

Para restringir sua chave de API a um ou mais apps Android, use uma das seguintes opções:

Console

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

    Ir para Credenciais

  2. Clique no nome da chave de API que você quer restringir.

  3. Na seção Restrições de aplicativo, selecione Apps Android.

  4. Para cada app Android que você quer adicionar, clique em Adicionar um item, insira o nome do pacote e a impressão digital do certificado SHA-1 e clique em Concluído.

  5. Clique em Salvar para salvar as mudanças e retornar à lista de chaves de API..

gcloud

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list para listar as chaves do projeto.

  2. Use o comando gcloud services api-keys update para especificar os apps Android que podem usar uma chave de API.

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restringir.

    • SHA1_FINGERPRINT e PACKAGE_NAME: as informações de um app Android que pode usar a chave.

      Você pode adicionar quantos apps quiser; use outras sinalizações --allowed-application.

    gcloud services api-keys update KEY_ID \
--allowed-application=sha1_fingerprint=SHA1_FINGERPRINT_1,package_name=PACKAGE_NAME_1 \
--allowed-application=sha1_fingerprint=SHA1_FINGERPRINT_2,package_name=PACKAGE_NAME_2

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.AndroidApplication;
import com.google.api.apikeys.v2.AndroidKeyRestrictions;
import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyAndroid {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyAndroid(projectId, keyId);
  }

  // Restricts an API key based on android applications.
  // Specifies the Android application that can use the key.
  public static void restrictApiKeyAndroid(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the allowed android applications.
      Restrictions restrictions = Restrictions.newBuilder()
          .setAndroidKeyRestrictions(AndroidKeyRestrictions.newBuilder()
              .addAllowedApplications(AndroidApplication.newBuilder()
                  // Specify the android application's package name and SHA1 fingerprint.
                  .setPackageName("com.google.appname")
                  .setSha1Fingerprint("0873D391E987982FBBD30873D391E987982FBBD3")
                  .build())
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_android(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key based on android applications.

    Specifies the Android application that can use the key.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Specify the android application's package name and SHA1 fingerprint.
    allowed_application = api_keys_v2.AndroidApplication()
    allowed_application.package_name = "com.google.appname"
    allowed_application.sha1_fingerprint = "0873D391E987982FBBD30873D391E987982FBBD3"

    # Restrict the API key usage by specifying the allowed applications.
    android_key_restriction = api_keys_v2.AndroidKeyRestrictions()
    android_key_restriction.allowed_applications = [allowed_application]

    # Set the restriction(s).
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.android_key_restrictions = android_key_restriction

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Você pode conseguir o ID usando o método keys.list. O ID é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"

  2. Use o método keys.patch para especificar os apps Android que podem usar uma chave de API.

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

    • SHA1_FINGERPRINT_1 e PACKAGE_NAME_1: as informações de um app Android que pode usar a chave.

      É possível adicionar as informações de quantos apps forem necessários. Use vírgulas para separar os objetos AndroidApplication. Você precisa fornecer a solicitação em todos os apps; aplicativos fornecidos substituem todos os aplicativos permitidos existentes na chave.

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

    • KEY_ID: o ID da chave que você quer restringir.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"restrictions" : {
"androidKeyRestrictions": {
  "allowedApplications": [
    {
      "sha1Fingerprint": "SHA1_FINGERPRINT_1",
      "packageName": "PACKAGE_NAME_1"
    },
 ]
}
}
}' \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Para mais informações sobre como adicionar restrições de app Android a uma chave usando a API REST, consulte Como adicionar restrições de Android, na documentação de API de chaves de API.

Apps iOS

É possível restringir o uso de uma chave de API a apps iOS específicos fornecendo o ID do pacote de cada app.

Ao usar a chave de API em uma solicitação, é preciso especificar o ID do pacote usando o cabeçalho HTTP X-Ios-Bundle-Identifier.

Para restringir sua chave de API a um ou mais apps iOS, use uma das seguintes opções:

Console

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

    Ir para Credenciais

  2. Clique no nome da chave de API que você quer restringir.

  3. Na seção Restrições de aplicativo, selecione Apps iOS.

  4. Para cada app iOS que você quer adicionar, clique em Adicionar um item, insira o ID do pacote e clique em Concluído.

  5. Clique em Salvar para salvar as mudanças e retornar à lista de chaves de API..

gcloud

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list para listar as chaves do projeto.

  2. Use o método gcloud services api-keys update para especificar os apps iOS que podem usar a chave.

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restringir.

    • ALLOWED_BUNDLE_ID: o ID do pacote de um app iOS que você quer que consiga usar essa chave de API.

      Você pode adicionar quantos IDs de pacote forem necessários. Use vírgulas para separar os IDs.

    gcloud services api-keys update KEY_ID \
--allowed-bundle-ids=ALLOWED_BUNDLE_ID_1,ALLOWED_BUNDLE_ID_2

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.IosKeyRestrictions;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.Arrays;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyIos {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyIos(projectId, keyId);
  }

  // Restricts an API key. You can restrict usage of an API key to specific iOS apps
  // by providing the bundle ID of each app.
  public static void restrictApiKeyIos(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the bundle ID(s)
      // of iOS app(s) that can use the key.
      Restrictions restrictions = Restrictions.newBuilder()
          .setIosKeyRestrictions(IosKeyRestrictions.newBuilder()
              .addAllAllowedBundleIds(Arrays.asList("com.google.gmail", "com.google.drive"))
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_ios(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. You can restrict usage of an API key to specific iOS apps
    by providing the bundle ID of each app.

    TODO(Developer): Replace the variables before running this sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the bundle ID(s) of iOS app(s) that can use the key.
    ios_key_restrictions = api_keys_v2.IosKeyRestrictions()
    ios_key_restrictions.allowed_bundle_ids = ["com.google.gmail", "com.google.drive"]

    # Set the API restriction.
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.ios_key_restrictions = ios_key_restrictions

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Você pode conseguir o ID usando o método keys.list. O ID é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"

  2. Use o método keys.patch para especificar os apps iOS que podem usar uma chave de API.

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

    • ALLOWED_BUNDLE_ID: o ID do pacote de um app iOS que pode usar a chave.

      É possível adicionar as informações de quantos apps forem necessários. use vírgulas para separar os IDs dos pacotes. É necessário fornecer todos os IDs de pacotes com a solicitação; os IDs de pacote fornecidos substituem todos os aplicativos permitidos existentes na chave.

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

    • KEY_ID: o ID da chave que você quer restringir.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"restrictions" : {
"iosKeyRestrictions": {
  "allowedBundleIds": ["ALLOWED_BUNDLE_ID_1","ALLOWED_BUNDLE_ID_2"]
}
}
}' \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Para mais informações sobre como adicionar restrições de app iOS a uma chave usando a API REST, consulte Como adicionar restrições de iOS, na documentação de API de chaves de API.

Adicionar restrições à API

Essas restrições especificam quais APIs podem ser chamadas com a chave de API.

Para adicionar restrições de API, use uma das seguintes opções:

Console

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

    Ir para Credenciais

  2. Clique no nome da chave de API que você quer restringir.

  3. Na seção Restrições de API, clique em Restringir chave.

  4. Selecione todas as APIs que usarão a chave de API para serem acessadas.

  5. Clique em Salvar para salvar as mudanças e retornar à lista de chaves de API..

gcloud

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list para listar as chaves do projeto.

  2. Use o comando gcloud services api-keys update para especificar em quais serviços uma chave de API pode ser usada para autenticação.

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restringir.

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

      É necessário fornecer todos os nomes de serviço com o comando update; os nomes de serviço fornecidos substituem todos os serviços existentes na chave.

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

    gcloud services api-keys update KEY_ID \
--api-target=service=SERVICE_1 --api-target=service=SERVICE_2

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.ApiTarget;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.Restrictions;
import com.google.api.apikeys.v2.UpdateKeyRequest;
import com.google.protobuf.FieldMask;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class RestrictApiKeyApi {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    String projectId = "GOOGLE_CLOUD_PROJECT_ID";

    // ID of the key to restrict. This ID is auto-created during key creation.
    // This is different from the key string. To obtain the key_id,
    // you can also use the lookup api: client.lookupKey()
    String keyId = "key_id";

    restrictApiKeyApi(projectId, keyId);
  }

  // Restricts an API key. Restrictions specify which APIs can be called using the API key.
  public static void restrictApiKeyApi(String projectId, String keyId)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Restrict the API key usage by specifying the target service and methods.
      // The API key can only be used to authenticate the specified methods in the service.
      Restrictions restrictions = Restrictions.newBuilder()
          .addApiTargets(ApiTarget.newBuilder()
              .setService("translate.googleapis.com")
              .addMethods("translate.googleapis.com.TranslateText")
              .build())
          .build();

      Key key = Key.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          // Set the restriction(s).
          // For more information on API key restriction, see:
          // https://cloud.google.com/docs/authentication/api-keys
          .setRestrictions(restrictions)
          .build();

      // Initialize request and set arguments.
      UpdateKeyRequest updateKeyRequest = UpdateKeyRequest.newBuilder()
          .setKey(key)
          .setUpdateMask(FieldMask.newBuilder().addPaths("restrictions").build())
          .build();

      // Make the request and wait for the operation to complete.
      Key result = apiKeysClient.updateKeyAsync(updateKeyRequest).get(3, TimeUnit.MINUTES);

      // For authenticating with the API key, use the value in "result.getKeyString()".
      System.out.printf("Successfully updated the API key: %s", result.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2
from google.cloud.api_keys_v2 import Key


def restrict_api_key_api(project_id: str, key_id: str) -> Key:
    """
    Restricts an API key. Restrictions specify which APIs can be called using the API key.

    TODO(Developer): Replace the variables before running the sample.

    Args:
        project_id: Google Cloud project id.
        key_id: ID of the key to restrict. This ID is auto-created during key creation.
            This is different from the key string. To obtain the key_id,
            you can also use the lookup api: client.lookup_key()

    Returns:
        response: Returns the updated API Key.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Restrict the API key usage by specifying the target service and methods.
    # The API key can only be used to authenticate the specified methods in the service.
    api_target = api_keys_v2.ApiTarget()
    api_target.service = "translate.googleapis.com"
    api_target.methods = ["transate.googleapis.com.TranslateText"]

    # Set the API restriction(s).
    # For more information on API key restriction, see:
    # https://cloud.google.com/docs/authentication/api-keys
    restrictions = api_keys_v2.Restrictions()
    restrictions.api_targets = [api_target]

    key = api_keys_v2.Key()
    key.name = f"projects/{project_id}/locations/global/keys/{key_id}"
    key.restrictions = restrictions

    # Initialize request and set arguments.
    request = api_keys_v2.UpdateKeyRequest()
    request.key = key
    request.update_mask = "restrictions"

    # Make the request and wait for the operation to complete.
    response = client.update_key(request=request).result()

    print(f"Successfully updated the API key: {response.name}")
    # Use response.key_string to authenticate.
    return response

REST

  1. Encontre o ID da chave que você quer restringir.

    O ID não é igual ao nome de exibição ou à string de chave. Você pode conseguir o ID usando o método keys.list. O ID é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/"

  2. Use o método keys.patch para especificar em quais serviços uma chave de API pode ser usada para autenticação.

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

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

      É necessário fornecer a solicitação a todos os nomes de serviço; os nomes de serviço fornecidos substituem todos os serviços existentes na chave.

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

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.

    • KEY_ID: o ID da chave que você quer restringir.

    curl -X PATCH \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
--data '{
"restrictions" : {
"apiTargets": [
  {
    "service": "SERVICE_1"
  },
  {
    "service" : "SERVICE_2"
  },
]
}
}' \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID?updateMask=restrictions"

Para mais informações sobre como adicionar restrições de API a uma chave usando a API REST, consulte Como adicionar restrições de API, na documentação de API de chaves de API.

Receber informações do projeto de uma string de chave

É possível determinar a que projeto do Google Cloud uma chave de API está associada por sua string.

Substitua KEY_STRING pela string de chave de que você precisa das informações do projeto.

gcloud

Use o comando gcloud services api-keys lookup para conseguir o ID do projeto em uma string de chave.

 gcloud services api-keys lookup KEY_STRING

Java

Para executar essa amostra, instale a biblioteca de cliente google-cloud-apikeys.


import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.LookupKeyRequest;
import com.google.api.apikeys.v2.LookupKeyResponse;
import java.io.IOException;

public class LookupApiKey {

  public static void main(String[] args) throws IOException {
    // TODO(Developer): Before running this sample,
    //  1. Replace the variable(s) below.
    //  2. Set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    //  3. Make sure you have the necessary permission to view API keys.
    // API key string to retrieve the API key name.
    String apiKeyString = "API_KEY_STRING";

    lookupApiKey(apiKeyString);
  }

  // Retrieves name (full path) of an API key using the API key string.
  public static void lookupApiKey(String apiKeyString) throws IOException {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests. After completing all of your requests, call
    // the `apiKeysClient.close()` method on the client to safely
    // clean up any remaining background resources.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Initialize the lookup request and set the API key string.
      LookupKeyRequest lookupKeyRequest = LookupKeyRequest.newBuilder()
          .setKeyString(apiKeyString)
          .build();

      // Make the request and obtain the response.
      LookupKeyResponse response = apiKeysClient.lookupKey(lookupKeyRequest);

      System.out.printf("Successfully retrieved the API key name: %s", response.getName());
    }
  }
}

Python

Para executar esta amostra, você precisa instalar a biblioteca de cliente de chaves de API.


from google.cloud import api_keys_v2


def lookup_api_key(api_key_string: str) -> None:
    """
    Retrieves name (full path) of an API key using the API key string.

    TODO(Developer):
    1. Before running this sample,
      set up ADC as described in https://cloud.google.com/docs/authentication/external/set-up-adc
    2. Make sure you have the necessary permission to view API keys.

    Args:
        api_key_string: API key string to retrieve the API key name.
    """

    # Create the API Keys client.
    client = api_keys_v2.ApiKeysClient()

    # Initialize the lookup request and set the API key string.
    lookup_key_request = api_keys_v2.LookupKeyRequest(
        key_string=api_key_string,
        # Optionally, you can also set the etag (version).
        # etag=etag,
    )

    # Make the request and obtain the response.
    lookup_key_response = client.lookup_key(lookup_key_request)

    print(f"Successfully retrieved the API key name: {lookup_key_response.name}")

REST

Use o método lookupKey para receber o ID do projeto em uma string de chave.

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://apikeys.googleapis.com/v2/keys:lookupKey?keyString=KEY_STRING"

Cancelar exclusão de uma chave de API

Se você excluir uma chave de API por engano, é possível cancelar a exclusão (restaurar) dessa chave até 30 dias após a exclusão. Após 30 dias, não é possível restaurar a chave de API.

Console

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

    Ir para Credenciais

  2. Clique em Restaurar credenciais excluídas.

  3. Encontre a chave de API excluída e clique em Restaurar.

    O cancelamento da exclusão da chave de API pode demorar alguns minutos para ser propagado. Após a propagação, a chave de API restaurada será exibida na lista de chaves de API.

gcloud

  1. Encontre o ID da chave que você quer restaurar.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o comando gcloud services api-keys list --show-deleted para listar as chaves excluídas do projeto.

  2. Use o comando gcloud services api-keys undelete para cancelar a exclusão de uma chave de API.

    gcloud services api-keys undelete KEY_ID

    Substitua os seguintes valores:

    • KEY_ID: o ID da chave que você quer restaurar.

REST

  1. Encontre o ID da chave que você quer restaurar.

    O ID não é igual ao nome de exibição ou à string de chave. Para conseguir o ID, use o método keys.list com o parâmetro de consulta showDeleted definido como true. O ID da chave é listado no campo uid da resposta.

    Substitua PROJECT_ID pelo ID ou número do projeto do Google Cloud.

    curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys?showDeleted=true"

  2. Use o método cancelar exclusão para cancelar a exclusão da chave de API.

    curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json; charset=utf-8" \
"https://apikeys.googleapis.com/v2/projects/PROJECT_ID/locations/global/keys/KEY_ID:undelete"

    Essa solicitação retorna uma operação de longa duração. Você precisa pesquisar a operação para saber quando ela é concluída e conferir o status dela.

    Substitua os seguintes valores:

    • PROJECT_ID: o nome ou ID do projeto do Google Cloud.
    • KEY_ID: o ID da chave que você quer restringir.

Pesquisar operações de longa duração

Os métodos de API de chaves de API usam operações de longa duração. Se você usar a API REST para criar e gerenciar chaves de API, um objeto de operação será retornado da solicitação do método inicial. Use o nome da operação para pesquisar a operação de longa duração. Quando a solicitação de longa duração é concluída, a pesquisa da operação retorna os dados da solicitação de longa duração.

Para pesquisar uma operação de API de chaves de API de longa duração, use o método operations.get.

Substitua OPERATION_NAME pelo nome da operação retornada pela operação de longa duração. Por exemplo, operations/akmf.p7-358517206116-cd10a88a-7740-4403-a8fd-979f3bd7fe1c.

curl -X GET \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json; charset=utf-8" \
    "https://apikeys.googleapis.com/v2/OPERATION_NAME"

Limites das chaves de API

É possível criar até 300 chaves de API por projeto. Esse é um limite do sistema e não pode ser alterado usando uma solicitação de aumento de cota.

Se mais chaves de API forem necessárias, use mais de um projeto.

A seguir