Administra claves de API

En esta página, se describe cómo crear, editar y restringir claves de API.

Introducción a las claves de API

Cuando usas una clave de API para autenticarte en una API, esta no identifica un principal. La clave de API asocia la solicitud con un proyecto de Google Cloud para fines de facturación y cuota. Sin un principal, la solicitud no puede usar Identity and Access Management (IAM) para verificar si el emisor tiene autorización para realizar la operación solicitada.

Una clave de API tiene los siguientes componentes, que se usan para administrar y usar la clave:

String
La string de clave de API es una string encriptada, por ejemplo, AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Cuando uses una clave de API para autenticar, siempre usarás la string de la clave. Las claves de API no tienen un archivo JSON asociado.
ID
Las herramientas administrativas de Google Cloud usan el ID de la clave de API para identificar de forma única la clave. No se puede usar el ID de clave para la autenticación. El ID de clave se puede encontrar en la URL de la página de edición de la clave en la consola de Google Cloud. También puedes obtener el ID de clave a través de Google Cloud CLI para enumerar las claves de tu proyecto.
Nombre visible
El nombre visible es un nombre descriptivo y opcional de la clave, que puedes configurar cuando creas o actualizas la clave.

Antes de comenzar

Completa las siguientes tareas para usar las muestras de esta página.

Configura la autenticación

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.

C++

Para usar las muestras de C++ de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

Java

Para usar las muestras de Java de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

Python

Para usar las muestras de Python de esta página en un entorno de desarrollo local, instala e inicializa gcloud CLI y, luego, configura las credenciales predeterminadas de la aplicación con tus credenciales de usuario.

  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.

Si deseas obtener más información, consulta Configura ADC para un entorno de desarrollo local en la documentación de autenticación de Google Cloud.

REST

Para usar las muestras de la API de REST en esta página en un entorno de desarrollo local, debes usar las credenciales que proporcionas a la CLI de gcloud.

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

    gcloud init

Si deseas obtener más información, consulta Autentica para usar REST en la documentación de autenticación de Google Cloud.

Roles obligatorios

Para obtener los permisos que necesitas para administrar las claves de API, pídele a tu administrador que te otorgue los siguientes roles de IAM en tu proyecto:

Para obtener más información sobre cómo otorgar roles, consulta Administra el acceso a proyectos, carpetas y organizaciones.

También puedes obtener los permisos necesarios mediante roles personalizados o cualquier otro rol predefinido.

Crea una clave de API

Para crear una clave de API, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en Crear credenciales y, luego, selecciona Clave de API en el menú.

    Se mostrará la string a la clave recién creada en el cuadro de diálogo Se creó la clave de API.

gcloud

Usa el comando gcloud services api-keys create para crear una clave de API.

Reemplaza DISPLAY_NAME por un nombre descriptivo para tu clave.

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

C++

Para ejecutar esta muestra, debes instalar la biblioteca cliente de claves de API.

#include "google/cloud/apikeys/v2/api_keys_client.h"
#include "google/cloud/location.h"

google::api::apikeys::v2::Key CreateApiKey(
    google::cloud::apikeys_v2::ApiKeysClient client,
    google::cloud::Location location, std::string display_name) {
  google::api::apikeys::v2::CreateKeyRequest request;
  request.set_parent(location.FullName());
  request.mutable_key()->set_display_name(std::move(display_name));
  // As an example, restrict the API key's scope to the Natural Language API.
  request.mutable_key()->mutable_restrictions()->add_api_targets()->set_service(
      "language.googleapis.com");

  // Create the key, blocking on the result.
  auto key = client.CreateKey(request).get();
  if (!key) throw std::move(key.status());
  std::cout << "Successfully created an API key: " << key->name() << "\n";

  // For authenticating with the API key, use the value in `key->key_string()`.

  // The API key's resource name is the value in `key->name()`. Use this to
  // refer to the specific key in a `GetKey()` or `DeleteKey()` RPC.
  return *key;
}

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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

Usarás el método keys.create para crear una clave de API. Esta solicitud muestra una operación de larga duración. Debes consultar la operación para obtener la información de la clave nueva.

Reemplaza los siguientes valores:

  • DISPLAY_NAME: Opcional Un nombre descriptivo para tu clave.
  • PROJECT_ID: el nombre o el ID de tu proyecto de 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 obtener más información sobre cómo crear claves de API con la API de REST, consulta Crea una clave de API en la documentación de la API de claves de API.

Copia tu string de clave y mantenla segura. Usa restricciones de claves de API para limitar la forma en que se puede usar la clave.

Aplica restricciones de claves de API

Las claves de API no están restringidas de forma predeterminada. Las claves no restringidas son inseguras porque cualquier persona puede usarlas desde cualquier lugar. Para las aplicaciones de producción, debes establecer restricciones de aplicaciones y restricciones de API.

Agrega restricciones de aplicaciones

Las restricciones de aplicaciones especifican qué sitios web, direcciones IP o apps pueden usar una clave de API.

Solo puedes aplicar un tipo de restricción de aplicación a la vez. Elige el tipo de restricción según el tipo de tu aplicación:

Opción Tipo de aplicación Notas
URL de referencia HTTP Aplicaciones web Especifica los sitios web que pueden usar la clave.
Direcciones IP Aplicaciones llamadas por servidores específicos Especifica los servidores o los trabajos cron que pueden usar la clave.
Apps para Android Aplicaciones para Android Especifica la aplicación para Android que puede usar la clave.
Apps para iOS Aplicaciones para iOS Especifica los paquetes de iOS que pueden usar la clave.

URL de referencia HTTP

Para restringir los sitios web que pueden usar tu clave de API, agrega una o más restricciones de referente HTTP.

Puedes reemplazar un carácter comodín (*) por el subdominio o la ruta, pero no puedes insertar un carácter comodín en el medio de la URL. Por ejemplo, *.example.com es válido y acepta todos los sitios que terminan en .example.com. Sin embargo, mysubdomain*.example.com no es una restricción válida.

Los números de puerto se pueden incluir en las restricciones de referente HTTP. Si incluyes un número de puerto, solo se detectarán coincidencias con las solicitudes que usen ese puerto. Si no especificas un número de puerto, las solicitudes de cualquier número de puerto coincidirán.

En la siguiente tabla, se muestran algunos ejemplos de situaciones y restricciones de navegador:

Situación Restricciones
Permite una URL específica Agrega una URL con una ruta de acceso exacta. Por ejemplo:
www.example.com/path
www.example.com/path/path

Algunos navegadores implementan una política de referencia que envía solo la URL de origen para las solicitudes de origen cruzado. Los usuarios de estos navegadores no pueden usar claves con restricciones de URL específicas de una página.

Permitir cualquier URL en tu sitio Debes establecer dos URLs en la lista allowedReferers.
  1. Es la URL para el dominio, sin un subdominio, y con un comodín en la ruta de acceso. Por ejemplo:
    example.com/*
  2. Una segunda URL que incluye un comodín para el subdominio y un comodín para la ruta. Por ejemplo:
    *.example.com/*
Permitir cualquier URL en un solo subdominio o dominio simple

Debes establecer dos URLs en la lista allowedReferers para permitir un dominio completo:

  1. Es la URL del dominio sin una barra diagonal final. Por ejemplo:
    www.example.com
    sub.example.com
    example.com
  2. Una segunda URL para el dominio que incluye un comodín en la ruta de acceso. Por ejemplo:
    www.example.com/*
    sub.example.com/*
    example.com/*

Para restringir tu clave de API a sitios web específicos, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en el nombre de la clave de API que deseas restringir.

  3. En la sección Restricciones de aplicaciones, selecciona URL de referencia HTTP.

  4. Para cada restricción que desees agregar, haz clic en Agregar un elemento, ingresa la restricción y haz clic en Listo.

  5. Haz clic en Guardar para guardar los cambios y volver a la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list para enumerar las claves de tu proyecto.

  2. Usa el comando gcloud services api-keys update para agregar restricciones de referentes HTTP a una clave de API.

    Reemplaza los siguientes valores:

    • KEY_ID: Es el ID de la clave que deseas restringir.

    • ALLOWED_REFERRER_1: Es la restricción de referente HTTP.

      Puedes agregar tantas restricciones como sea necesario. Usa comas para separar las restricciones. Debes proporcionar todas las restricciones de referencia con el comando update. Las restricciones de referencia que se proporcionan reemplazan cualquier restricción de referencia existente en la clave.

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

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list. El ID se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método keys.patch para agregar restricciones de referentes HTTP a la clave de API.

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • ALLOWED_REFERRER_1: Es la restricción de referente HTTP.

      Puedes agregar tantas restricciones como sea necesario. Usa comas para separar las restricciones. Debes proporcionar todas las restricciones de referencia con la solicitud. Las restricciones de referencia que se proporcionan reemplazan cualquier restricción de referencia existente en la clave.

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.

    • KEY_ID: Es el ID de la clave que deseas 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 obtener más información sobre cómo agregar restricciones de referentes HTTP a una clave mediante la API de REST, consulta Agrega restricciones de navegador en la documentación de la API de claves de API.

Direcciones IP

Puedes especificar una o más direcciones IP de los emisores, como un servidor web o un trabajo cron, que tienen permiso para usar tu clave de API. Puedes especificar las direcciones IP en cualquiera de los siguientes formatos:

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • Una subred con notación CIDR (198.51.100.0/24, 2001:db8::/64)

El uso de localhost no es compatible con las restricciones del servidor.

Para restringir tu clave de API a direcciones IP específicas, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en el nombre de la clave de API que deseas restringir.

  3. En la sección Restricciones de aplicaciones, selecciona Direcciones IP.

  4. Por cada dirección IP que desees agregar, haz clic en Agregar un elemento, ingresa la dirección y haz clic en Listo.

  5. Haz clic en Guardar para guardar los cambios y volver a la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list para enumerar las claves de tu proyecto.

  2. Usa el comando gcloud services api-keys update para agregar restricciones de servidor (dirección IP) a una clave de API.

    Reemplaza los siguientes valores:

    • KEY_ID: Es el ID de la clave que deseas restringir.

    • ALLOWED_IP_ADDR_1: La dirección IP permitida.

      Puedes agregar tantas direcciones IP como sea necesario. Usa comas para separar las direcciones.

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

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list. El ID se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método keys.patch para agregar restricciones de servidor (dirección IP) a una clave de API.

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • ALLOWED_IP_ADDR_1: La dirección IP permitida.

      Puedes agregar tantas direcciones IP como sea necesario. Usa comas para separar las restricciones. Debes proporcionar todas las direcciones IP con la solicitud. Las restricciones de referente proporcionadas reemplazan cualquier restricción de dirección IP existente en la clave.

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.

    • KEY_ID: Es el ID de la clave que deseas 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 obtener más información sobre cómo agregar restricciones de direcciones IP a una clave mediante la API de REST, consulta Agrega restricciones de servidores en la documentación de la API de claves de API.

Apps para Android

Puedes restringir el uso de una clave de API a apps para Android específicas. Debes proporcionar el nombre del paquete y la huella digital del certificado SHA-1 de 20 bytes para cada app.

Cuando usas la clave de API en una solicitud, debes especificar el nombre del paquete y la huella digital del certificado con los siguientes encabezados HTTP:

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

Para restringir tu clave de API a una o más apps para Android, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en el nombre de la clave de API que deseas restringir.

  3. En la sección Restricciones de aplicaciones, selecciona Apps para Android.

  4. Por cada app para Android que desees agregar, haz clic en Agregar un elemento y, luego, ingresa el nombre del paquete y la huella digital del certificado SHA-1. Luego, haz clic en Listo.

  5. Haz clic en Guardar para guardar los cambios y volver a la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list para enumerar las claves de tu proyecto.

  2. Usa el comando gcloud services api-keys update para especificar las apps para Android que pueden usar una clave de API.

    Reemplaza los siguientes valores:

    • KEY_ID: Es el ID de la clave que deseas restringir.

    • SHA1_FINGERPRINT y PACKAGE_NAME: Es la información de una app de Android que puede usar la clave.

      Puedes agregar tantas apps como sea necesario. Usa marcas --allowed-application adicionales.

    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 ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list. El ID se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método keys.patch para especificar las apps para Android que pueden usar una clave de API.

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • SHA1_FINGERPRINT_1 y PACKAGE_NAME_1: Es la información de una app de Android que puede usar la clave.

      Puedes agregar la información para tantas aplicaciones como sea necesario. Usa comas para separar los objetos AndroidApplication. Debes proporcionar todas las aplicaciones con la solicitud. Las aplicaciones proporcionadas reemplazan cualquier aplicación permitida existente en la clave.

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.

    • KEY_ID: Es el ID de la clave que deseas 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 obtener más información sobre cómo agregar restricciones de apps para Android a una clave mediante la API de REST, consulta Agrega restricciones de Android en la documentación de la API de claves de API.

Apps para iOS

Puedes restringir el uso de una clave de API a apps para iOS específicas si proporcionas el ID del paquete de cada app.

Cuando usas la clave de API en una solicitud, debes especificar el ID del paquete con el encabezado HTTP X-Ios-Bundle-Identifier.

Para restringir tu clave de API a una o más apps para iOS, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en el nombre de la clave de API que deseas restringir.

  3. En la sección Restricciones de aplicaciones, selecciona Apps para iOS.

  4. Por cada app para iOS que desees agregar, haz clic en Agregar un elemento, ingresa el ID del paquete y, luego, haz clic en Listo.

  5. Haz clic en Guardar para guardar los cambios y volver a la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list para enumerar las claves de tu proyecto.

  2. Usa el método gcloud services api-keys update para especificar las apps para iOS que pueden usar la clave.

    Reemplaza los siguientes valores:

    • KEY_ID: Es el ID de la clave que deseas restringir.

    • ALLOWED_BUNDLE_ID: El ID del paquete de una app para iOS que deseas que pueda usar esta clave de API.

      Puedes agregar tantos ID del paquete como sea necesario. Usa comas para separar los IDs.

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

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list. El ID se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método keys.patch para especificar las apps para iOS que pueden usar una clave de API.

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • ALLOWED_BUNDLE_ID: El ID del paquete de una app para iOS que puede usar la clave.

      Puedes agregar la información para tantas aplicaciones como sea necesario. Usa comas para separar los ID del paquete. Debes proporcionar todos los ID del paquete con la solicitud. Los ID del paquete proporcionados reemplazan cualquier aplicación permitida existente en la clave.

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.

    • KEY_ID: Es el ID de la clave que deseas 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 obtener más información sobre cómo agregar restricciones de apps para iOS a una clave mediante la API de REST, consulta Agrega restricciones de iOS en la documentación de la API de claves de API.

Agrega restricciones de API

Las restricciones de API especifican a qué API se puede llamar mediante la clave de API.

Para agregar restricciones de API, usa una de las siguientes opciones:

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en el nombre de la clave de API que deseas restringir.

  3. En la sección Restricciones de API, haz clic en Restringir clave .

  4. Selecciona todas las APIs a las que se usará tu clave de API para acceder.

  5. Haz clic en Guardar para guardar los cambios y volver a la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list para enumerar las claves de tu proyecto.

  2. Usa el comando gcloud services api-keys update para especificar en qué servicios se puede usar una clave de API a fin de autenticarse.

    Reemplaza los siguientes valores:

    • KEY_ID: Es el ID de la clave que deseas restringir.

    • SERVICE_1, SERVICE_2…: Los nombres de los servicios de las APIs a las que se puede acceder la clave.

      Debes proporcionar todos los nombres de los servicios con el comando update. Los nombres de los servicios proporcionados reemplazan cualquier servicio existente en la clave.

    Para encontrar el nombre del servicio, busca la API en el panel de la API. Los nombres de servicios son strings como bigquery.googleapis.com.

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

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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. Obtén el ID de la clave que deseas restringir.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list. El ID se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método keys.patch para especificar en qué servicios se puede usar una clave de API a fin de autenticarse.

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • SERVICE_1, SERVICE_2…: Los nombres de los servicios de las APIs a las que se puede acceder la clave.

      Debes proporcionar todos los nombres de servicios con la solicitud. Los nombres de los servicios proporcionados reemplazan cualquier servicio existente en la clave.

      Para encontrar el nombre del servicio, busca la API en el panel de la API. Los nombres de servicios son strings como bigquery.googleapis.com.

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.

    • KEY_ID: Es el ID de la clave que deseas 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 obtener más información sobre cómo agregar restricciones de API a una clave mediante la API de REST, consulta Agrega restricciones de API en la documentación de la API de claves de API.

Obtén información del proyecto a partir de una string de clave

Puedes determinar con qué proyecto de Google Cloud se asocia una clave de API desde su string.

Reemplaza KEY_STRING por la string de clave para la que necesitas información del proyecto.

gcloud

Usa el comando gcloud services api-keys lookup para obtener el ID del proyecto de una cadena de clave.

 gcloud services api-keys lookup KEY_STRING

Java

Para ejecutar esta muestra, debes instalar la biblioteca 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 ejecutar esta muestra, debes instalar la biblioteca cliente de claves 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

Usa el método lookupKey para obtener el ID del proyecto de una string de clave.

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"

Recuperar una clave de API

Si borras una clave de API por error, puedes recuperarla (en un plazo de 30 días después de borrarla). Después de 30 días, no puedes recuperar la clave de API.

Console

  1. En la consola de Google Cloud, ve a la página Credenciales.

    Ir a Credenciales

  2. Haz clic en Restablecer credenciales borradas.

  3. Busca la clave de API borrada que deseas recuperar y haz clic en Restablecer.

    La recuperación de una clave de API puede tardar unos minutos en propagarse. Después de la propagación, la clave de API recuperada se muestra en la lista de claves de API.

gcloud

  1. Obtén el ID de la clave que deseas reperar.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el comando gcloud services api-keys list --show-deleted para enumerar las claves de tu proyecto.

  2. Usa el comando gcloud services api-keys undelete para recuperar una clave de API.

    gcloud services api-keys undelete KEY_ID

    Reemplaza los siguientes valores:

    • KEY_ID: El ID de la clave que deseas restringir.

Java

Para ejecutar esta muestra, debes instalar la biblioteca cliente google-cloud-apikeys.

import com.google.api.apikeys.v2.ApiKeysClient;
import com.google.api.apikeys.v2.Key;
import com.google.api.apikeys.v2.UndeleteKeyRequest;
import java.io.IOException;
import java.util.concurrent.ExecutionException;
import java.util.concurrent.TimeUnit;
import java.util.concurrent.TimeoutException;

public class UndeleteApiKey {

  public static void main(String[] args)
      throws IOException, ExecutionException, InterruptedException, TimeoutException {
    // TODO(developer): Replace these variables before running the sample.
    // Project ID or project number of the Google Cloud project.
    String projectId = "YOUR_PROJECT_ID";
    // The API key id to undelete.
    String keyId = "YOUR_KEY_ID";

    undeleteApiKey(projectId, keyId);
  }

  // Undeletes an API key.
  public static void undeleteApiKey(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.
    try (ApiKeysClient apiKeysClient = ApiKeysClient.create()) {

      // Initialize the undelete request and set the argument.
      UndeleteKeyRequest undeleteKeyRequest = UndeleteKeyRequest.newBuilder()
          .setName(String.format("projects/%s/locations/global/keys/%s", projectId, keyId))
          .build();

      // Make the request and wait for the operation to complete.
      Key undeletedKey = apiKeysClient.undeleteKeyAsync(undeleteKeyRequest)
          .get(3, TimeUnit.MINUTES);

      System.out.printf("Successfully undeleted the API key: %s", undeletedKey.getName());
    }
  }
}

REST

  1. Obtén el ID de la clave que deseas reperar.

    El ID no es el mismo que el nombre visible o la string de clave. Puedes obtener el ID mediante el método keys.list y el parámetro de consulta showDeleted configurado como true. El ID de clave se enumera en el campo uid de la respuesta.

    Reemplaza PROJECT_ID por el ID o el nombre de tu proyecto de 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. Usa el método undelete para recuperar la clave 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"

    Esta solicitud muestra una operación de larga duración. Debes sondear la operación para saber cuándo se completa y obtener su estado.

    Reemplaza los siguientes valores:

    • PROJECT_ID: el nombre o el ID de tu proyecto de Google Cloud.
    • KEY_ID: Es el ID de la clave que deseas restringir.

Sondea operaciones de larga duración

Los métodos de API de la clave de API usan operaciones de larga duración. Si usas la API de REST para crear y administrar claves de API, se muestra un objeto de operación a partir de la solicitud del método inicial. Usa el nombre de la operación para sondear la operación de larga duración. Cuando se completa la solicitud de larga duración, el sondeo de la operación muestra los datos de la solicitud de larga duración.

Para sondear una operación de API de claves de API de larga duración, usa el método operations.get.

Reemplaza OPERATION_NAME por el nombre de la operación que muestra la operación de larga duración. Por ejemplo, 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"

Límites de las claves de API

Puedes crear hasta 300 claves de API por proyecto. Este es un límite del sistema y no se puede cambiar mediante una solicitud de aumento de cuota. Si se necesitan más claves de API, debes usar más de un proyecto.

Puedes agregar hasta 1,200 restricciones de aplicación a una clave de API.

¿Qué sigue?