S'authentifier à l'aide de clés API

Cette page explique comment utiliser des clés API pour s'authentifier auprès des API Google Cloud et des services compatibles avec les clés API.

La plupart des API Google Cloud ne sont pas compatibles avec les clés API. Vérifiez que l'API que vous souhaitez utiliser est compatible avec les clés API avant d'utiliser cette méthode d'authentification.

Pour en savoir plus sur l'utilisation des clés API pour vous authentifier auprès de Google Maps Platform, consultez la documentation de Google Maps Platform. Pour plus d'informations sur l'API API Keys, consultez la documentation de l'API API Keys.

Présentation des clés API

Lorsque vous utilisez une clé API pour vous authentifier auprès d'une API, la clé API n'identifie pas de compte principal et ne fournit pas non plus d'informations relatives à l'autorisation. Par conséquent, la requête n'utilise pas Identity and Access Management (IAM) pour vérifier si l'appelant est autorisé à effectuer l'opération demandée.

La clé API associe la requête à un projet Google Cloud, à des fins de facturation et de quotas. Étant donné que les clés API n'identifient pas l'appelant, elles sont souvent utilisées pour accéder à des données ou aux ressources publiques.

De nombreuses API Google Cloud n'acceptent pas les clés API pour l'authentification. Consultez la documentation sur l'authentification concernant le service ou l'API que vous souhaitez utiliser pour déterminer s'il est compatible avec les clés API.

Une clé API comprend les composants suivants, que vous utilisez pour gérer et utiliser la clé :

Chaîne
La chaîne de clé API est une chaîne chiffrée, par exemple AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe. Lorsque vous utilisez une clé API pour l'authentification, vous utilisez toujours la chaîne de la clé. Les clés API ne sont pas associées à un fichier JSON.
ID
L'ID de clé API est utilisé par les outils d'administration de Google Cloud pour identifier de manière unique la clé. Vous ne pouvez pas vous authentifier à l'aide de l'ID de clé. Vous pouvez trouver l'ID de la clé dans l'URL de la page de modification de la clé dans la console Google Cloud. Vous pouvez également obtenir l'ID de clé à l'aide de Google Cloud CLI pour répertorier les clés de votre projet.
Nom à afficher
Le nom à afficher est un nom descriptif facultatif pour la clé, que vous pouvez définir lorsque vous créez ou mettez à jour la clé.

Pour gérer les clés API, vous devez disposer du rôle d'administrateur de clés API (roles/serviceusage.apiKeysAdmin) sur le projet.

Avant de commencer

Sélectionnez l'onglet correspondant à la façon dont vous prévoyez d'utiliser les exemples de cette page :

Console

Lorsque vous utilisez la console Google Cloud pour accéder aux services et aux API Google Cloud, vous n'avez pas besoin de configurer l'authentification.

gcloud

Vous pouvez utiliser les exemples gcloud CLI de cette page dans l'un des environnements de développement suivants :

  • Cloud Shell : pour utiliser un terminal en ligne avec gcloud CLI déjà configuré, activez Cloud Shell.

    En bas de cette page, une session Cloud Shell démarre et affiche une invite de ligne de commande. L'initialisation de la session peut prendre quelques secondes.

  • Shell local : pour utiliser gcloud CLI dans un environnement de développement local, installez et initialisez gcloud CLI.

Java

Pour utiliser les exemples Java de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

  1. Install the Google Cloud CLI.

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

    gcloud init

  3. Create local authentication credentials for your user account: 

    gcloud auth application-default login

Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local dans la documentation sur l'authentification Google Cloud.

Python

Pour utiliser les exemples Python de cette page dans un environnement de développement local, installez et initialisez gcloud CLI, puis configurez le service Identifiants par défaut de l'application à l'aide de vos identifiants utilisateur.

  1. Install the Google Cloud CLI.

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

    gcloud init

  3. Create local authentication credentials for your user account: 

    gcloud auth application-default login

Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local dans la documentation sur l'authentification Google Cloud.

REST

Pour utiliser les exemples d'API REST de cette page dans un environnement de développement local, vous devez utiliser les identifiants que vous fournissez à gcloud CLI.

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

    gcloud init

Créer une clé API

Appliquez l'une des procédures suivantes pour créer une clé API.

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur Créer des identifiants, puis sélectionnez Clé API dans le menu.

    La boîte de dialogue Clé API créée affiche la chaîne correspondant à la clé que vous venez de créer.

gcloud

Vous exécutez la commande gcloud services api-keys create pour créer une clé API.

Remplacez DISPLAY_NAME par un nom descriptif pour votre clé.

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

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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

Vous utilisez la méthode keys.create pour créer une clé API. Cette requête renvoie une opération de longue durée, que vous devez interroger pour obtenir les informations de la nouvelle clé.

Remplacez les valeurs suivantes :

  • DISPLAY_NAME : facultatif. Un nom descriptif pour votre clé.
  • PROJECT_ID : ID ou nom de votre projet 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"

Pour plus d'informations sur la création de clés API à l'aide de l'API REST, consultez la page Créer une clé API dans la documentation de l'API "API Keys".

Copiez votre chaîne de clé et conservez-la à un emplacement sécurisé. Si vous n'utilisez pas une clé de test que vous prévoyez de supprimer ultérieurement, ajoutez des restrictions d'application et de clé API.

Utiliser une clé API

Si une API est compatible avec les clés API, vous pouvez l'authentifier à l'aide de clés API. Vous pouvez utiliser des clés API avec des requêtes REST et avec les bibliothèques clientes qui les prennent en charge.

Utiliser une clé API avec REST

Vous pouvez transmettre la clé API dans un appel d'API REST en tant que paramètre de requête, au format suivant. Remplacez API_KEY par la chaîne de votre clé API.

Par exemple, afin de transmettre une clé API pour une requête API Cloud Natural Language pour documents.analyzeEntities, procédez comme suit :

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

Vous pouvez également utiliser l'en-tête x-goog-api-key pour transmettre votre clé. Cet en-tête doit être utilisé avec les requêtes 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"

Utiliser une clé API avec des bibliothèques clientes

La compatibilité des bibliothèques clientes avec les clés API est spécifique à un langage.

Python

Cet exemple utilise l'API Cloud Natural Language, qui est compatible avec les clés API pour l'authentification, afin de vous montrer comment fournir une clé API à la bibliothèque.

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente Natural Language et la bibliothèque cliente des clés API.


from google.cloud import language_v1


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

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

    Args:
        quota_project_id: Google Cloud project id that should be used for quota and billing purposes.
        api_key_string: The API key to authenticate to the service.
    """

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

    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")

Sécuriser une clé API

Lorsque vous utilisez des clés API dans vos applications, assurez-vous qu'elles sont protégées lors du stockage et de la transmission. L'exposition publique de vos clés API peut entraîner des frais inattendus. Pour contribuer à la sécurité de vos clés API, appliquez les bonnes pratiques suivantes :

  • Ajoutez des restrictions de clés API à votre clé.

    En ajoutant des restrictions, vous pouvez limiter les modalités d'utilisation d'une clé API, réduisant ainsi l'impact d'une clé API compromise.

  • Supprimez les clés API inutiles pour réduire l'exposition aux attaques.

  • Recréez régulièrement vos clés API.

    Vous devez créer périodiquement des clés API, supprimer les anciennes et mettre à jour vos applications pour qu'elles utilisent les nouvelles clés API.

Appliquer des restrictions liées aux clés API

Les clés API ne sont pas restreintes par défaut. Les clés sans restriction ne sont pas sécurisées, car elles peuvent être utilisées par n'importe qui et depuis n'importe quel emplacement. Pour les applications de production, vous devez définir des restrictions d'application et des restrictions d'API.

Ajouter des restrictions liées aux applications

Les restrictions relatives aux applications spécifient les sites Web, adresses IP ou applications qui peuvent utiliser une clé API.

Vous ne pouvez appliquer qu'un seul type de restriction d'application à la fois. Choisissez le type de restriction en fonction du type de votre application :

Option Application type (Type d'application) Remarques
Référents HTTP Applications Web Spécifie les sites Web pouvant utiliser la clé.
Adresses IP Applications appelées par des serveurs spécifiques Spécifie les serveurs ou les jobs Cron pouvant utiliser la clé.
Applications Android Applications Android Spécifie l'application Android pouvant utiliser la clé.
Applications iOS Applications iOS Spécifie les groupes iOS pouvant utiliser la clé.

Référents HTTP

Pour limiter les sites Web autorisés à utiliser votre clé API, vous pouvez ajouter une ou plusieurs restrictions de référents HTTP.

Vous pouvez remplacer un sous-domaine ou un chemin d'accès par un caractère générique (*), mais vous ne pouvez pas insérer de caractère générique au milieu de l'URL. Par exemple, la valeur *.example.com est valide et accepte tous les sites se terminant par .example.com. En revanche, mysubdomain*.example.com n'est pas une restriction valide.

Les numéros de ports peuvent être inclus dans les restrictions de référents HTTP. Si vous incluez un numéro de port, seules les requêtes utilisant ce port sont prises en compte. Si vous ne spécifiez pas de numéro de port, les requêtes exploitant n'importe quel numéro de port sont prises en compte.

Vous pouvez ajouter jusqu'à 1 200 référents HTTP à une clé API.

Le tableau suivant présente quelques exemples de scénarios, et décrit les restrictions correspondantes appliquées dans le navigateur :

Scénario Restrictions
Autoriser une URL spécifique Vous devez ajoutez une URL avec un chemin d'accès exact. Exemple :
www.example.com/path
www.example.com/path/path

Certains navigateurs mettent en œuvre une règle d'URL de provenance qui envoie uniquement l'URL d'origine pour les requêtes d'origines multiples. Les utilisateurs de ces navigateurs ne peuvent pas utiliser de clés avec des restrictions d'URL spécifiques à la page.

Autoriser n'importe quelle URL de votre site Vous devez définir deux URL dans la liste allowedReferers.
  1. URL du domaine, sans sous-domaine et avec un caractère générique représentant le chemin d'accès. Par exemple :
    example.com/*
  2. Une deuxième URL comprenant un caractère générique pour le sous-domaine et un caractère générique pour le chemin d'accès. Par exemple :
    *.example.com/*
Autoriser n'importe quelle URL dans un seul sous-domaine ou domaine nu

Vous devez définir deux URL dans la liste allowedReferers pour autoriser l'ensemble d'un domaine :

  1. URL du domaine, sans barre oblique finale. Exemple :
    www.example.com
    sub.example.com
    example.com
  2. Une deuxième URL pour le domaine, qui inclut un caractère générique pour le chemin d'accès. Exemple :
    www.example.com/*
    sub.example.com/*
    example.com/*

Pour limiter votre clé API à des sites Web spécifiques, utilisez l'une des options suivantes :

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur le nom de la clé API que vous souhaitez restreindre.

  3. Dans la section Restrictions liées aux applications, sélectionnez Référents HTTP.

  4. Pour chaque restriction que vous souhaitez ajouter, cliquez sur Ajouter un élément, saisissez la restriction, puis cliquez sur OK.

  5. Cliquez sur Enregistrer pour enregistrer vos modifications et revenir à la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list pour lister les clés de votre projet.

  2. Exécutez la commande gcloud services api-keys update pour ajouter des restrictions d'URL de provenance HTTP à une clé API.

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    • ALLOWED_REFERRER_1 : votre restriction de référent HTTP.

      Vous pouvez ajouter autant de restrictions que nécessaire, en utilisant des virgules pour les séparer. Vous devez fournir toutes les restrictions de référents avec la commande update ; les restrictions de référents ainsi fournies remplacent toutes les restrictions de référents existantes sur la clé.

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

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode keys.patch pour ajouter des restrictions de référents HTTP à la clé API.

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • ALLOWED_REFERRER_1 : votre restriction de référent HTTP.

      Vous pouvez ajouter autant de restrictions que nécessaire, en utilisant des virgules pour les séparer. Vous devez fournir toutes les restrictions de référents avec la requête. les restrictions de référent ainsi fournies remplacent toutes les restrictions de référents existantes sur la clé.

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    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"

Pour en savoir plus sur l'ajout à une clé de restrictions sur les URL de provenance HTTP, à l'aide de l'API REST, consultez la section Ajouter des restrictions de navigateur dans la documentation de l'API "API Keys".

Adresses IP

Vous pouvez spécifier une ou plusieurs adresses IP pour les appelants, tels qu'un serveur Web ou un job Cron, qui sont autorisés à utiliser votre clé API. Vous pouvez spécifier les adresses IP dans l'un des formats suivants :

  • IPv4 (198.51.100.1)
  • IPv6 (2001:db8::1)
  • Un sous-réseau utilisant la notation CIDR (198.51.100.0/24, 2001:db8::/64)

L'utilisation de localhost n'est pas compatible avec les restrictions de serveur.

Pour limiter votre clé API à des adresses IP spécifiques, utilisez l'une des options suivantes :

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur le nom de la clé API que vous souhaitez restreindre.

  3. Dans la section Restrictions liées aux applications, sélectionnez Adresses IP.

  4. Pour chaque adresse IP que vous souhaitez ajouter, cliquez sur Ajouter un élément, saisissez l'adresse, puis cliquez sur OK.

  5. Cliquez sur Enregistrer pour enregistrer vos modifications et revenir à la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list pour lister les clés de votre projet.

  2. Exécutez la commande gcloud services api-keys update pour ajouter des restrictions de serveur (adresse IP) à une clé API.

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    • ALLOWED_IP_ADDR_1 : votre adresse IP autorisée.

      Vous pouvez ajouter autant d'adresses IP que nécessaire, en les séparant par des virgules.

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

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode keys.patch pour ajouter des restrictions de serveur (adresse IP) à une clé API.

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • ALLOWED_IP_ADDR_1 : votre adresse IP autorisée.

      Vous pouvez ajouter autant d'adresses IP que nécessaire, en séparant les restrictions ainsi définies par des virgules. Vous devez fournir toutes les adresses IP avec la requête. Les restrictions fournies remplacent toutes les restrictions d'adresse IP existantes sur la clé.

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    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"

Pour en savoir plus sur l'ajout à une clé de restrictions d'adresse IP à l'aide de l'API REST, consultez la section Ajouter des restrictions de serveur dans la documentation de l'API "API Keys".

Applications Android

Vous pouvez limiter l'utilisation d'une clé API à des applications Android spécifiques. Vous devez indiquer le nom du package et l'empreinte de 20 octets du certificat SHA-1 pour chaque application.

Lorsque vous utilisez la clé API dans une requête, vous devez spécifier le nom du package et l'empreinte du certificat à l'aide des en-têtes HTTP suivants :

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

Pour limiter votre clé API à une ou plusieurs applications Android, appliquez l'une des procédures suivantes.

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur le nom de la clé API que vous souhaitez restreindre.

  3. Dans la section Restrictions liées aux applications, sélectionnez Applications Android.

  4. Pour chaque application Android que vous souhaitez ajouter, cliquez sur Ajouter un élément, saisissez le nom du package et l'empreinte du certificat SHA-1, puis cliquez sur OK.

  5. Cliquez sur Enregistrer pour enregistrer vos modifications et revenir à la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list pour lister les clés de votre projet.

  2. Exécutez la commande gcloud services api-keys update pour spécifier les applications Android pouvant utiliser une clé API.

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    • SHA1_FINGERPRINT et PACKAGE_NAME : informations relatives à une application Android pouvant utiliser la clé.

      Vous pouvez ajouter autant d'applications que nécessaire, en utilisant des options --allowed-application supplémentaires.

    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

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode keys.patch pour spécifier les applications Android pouvant utiliser une clé API.

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • SHA1_FINGERPRINT_1 et PACKAGE_NAME_1 : informations relatives à une application Android pouvant utiliser la clé.

      Vous pouvez ajouter des informations pour autant d'applications que nécessaire, en utilisant des virgules pour séparer les objets AndroidApplication. Vous devez fournir toutes les applications avec la requête. Les applications fournies remplacent toutes les applications autorisées existantes sur la clé.

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    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"

Pour en savoir plus sur l'ajout à une clé de restrictions sur les applications Android, à l'aide de l'API REST, consultez la section Ajouter des restrictions Android dans la documentation de l'API "API Keys".

Applications iOS

Vous pouvez restreindre l'utilisation d'une clé API à des applications iOS spécifiques en fournissant l'ID du bundle de chaque application.

Lorsque vous utilisez la clé API dans une requête, vous devez spécifier l'ID de groupe à l'aide de l'en-tête HTTP X-Ios-Bundle-Identifier.

Pour limiter votre clé API à une ou plusieurs applications iOS, appliquez l'une des procédures suivantes.

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur le nom de la clé API que vous souhaitez restreindre.

  3. Dans la section Restrictions liées aux applications, sélectionnez Applications iOS.

  4. Pour chaque application iOS que vous souhaitez ajouter, cliquez sur Ajouter un élément, saisissez l'ID du bundle, puis cliquez sur OK.

  5. Cliquez sur Enregistrer pour enregistrer vos modifications et revenir à la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list pour lister les clés de votre projet.

  2. Utilisez la méthode gcloud services api-keys update pour spécifier les applications iOS pouvant utiliser la clé.

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    • ALLOWED_BUNDLE_ID : ID de bundle d'une application iOS qui doit pouvoir utiliser cette clé API.

      Vous pouvez ajouter autant d'ID de bundle que nécessaire, en les séparant par des virgules.

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

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode keys.patch pour spécifier les applications iOS pouvant utiliser une clé API.

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • ALLOWED_BUNDLE_ID : ID de bundle d'une application iOS pouvant utiliser la clé.

      Vous pouvez ajouter les informations pour autant d'applications que nécessaire ; utilisez des virgules pour séparer les ID de groupe. Vous devez fournir tous les ID de groupe avec la requête ; les ID de groupe fournis remplacent les applications autorisées existantes sur la clé.

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    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"

Pour en savoir plus sur l'ajout à une clé de restrictions sur les applications iOS, à l'aide de l'API REST, consultez la section Ajouter des restrictions iOS dans la documentation de l'API "API Keys".

Ajouter des restrictions liées aux API

Les restrictions relatives aux API définissent les API qui peuvent être appelées à l'aide de la clé API.

Appliquez l'une des procédures suivantes pour ajouter des restrictions liées aux API.

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur le nom de la clé API que vous souhaitez restreindre.

  3. Dans la section Restrictions relatives aux API, cliquez sur Restreindre la clé.

  4. Sélectionnez toutes les API dont l'accès nécessitera votre clé API.

  5. Cliquez sur Enregistrer pour enregistrer vos modifications et revenir à la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list pour lister les clés de votre projet.

  2. Spécifiez les services au niveau desquels une clé API peut être utilisée pour l'authentification à l'aide de la commande gcloud services api-keys update.

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    • SERVICE_1, SERVICE_2 : noms des services des API auxquels la clé peut accéder.

      Vous devez fournir tous les noms de services via la commande update ; Les noms de services fournis remplacent tous les services existants sur la clé.

    Vous pouvez trouver le nom du service en recherchant l'API sur le tableau de bord des API. Les noms de service sont des chaînes telles que bigquery.googleapis.com.

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

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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. Obtenez l'ID de la clé que vous souhaitez restreindre.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode keys.patch pour indiquer les services auprès desquels il est possible de s'authentifier à l'aide d'une clé API.

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • SERVICE_1, SERVICE_2 : noms des services des API auxquels la clé peut accéder.

      Vous devez fournir tous les noms de services dans la requête ; ceux-ci remplacent tous les services existants sur la clé.

      Vous pouvez trouver le nom du service en recherchant l'API sur le tableau de bord des API. Les noms de service sont des chaînes telles que bigquery.googleapis.com.

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.

    • KEY_ID : ID de la clé que vous souhaitez restreindre.

    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"

Pour en savoir plus sur l'ajout à une clé de restrictions sur les API, à l'aide de l'API REST, consultez la section Ajouter des restrictions d'API dans la documentation de l'API "API Keys".

Obtenir des informations sur le projet à partir d'une chaîne de clé

Vous pouvez déterminer à quel projet Google Cloud une clé API est associée à partir de sa chaîne.

Remplacez KEY_STRING par la chaîne de clé pour laquelle vous souhaitez identifier le projet associé.

gcloud

Exécutez la commande gcloud services api-keys lookup pour obtenir l'ID du projet à partir d'une chaîne de clé.

 gcloud services api-keys lookup KEY_STRING

Java

Pour exécuter cet exemple, vous devez installer la bibliothèque 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

Pour exécuter cet exemple, vous devez installer la bibliothèque cliente des clés 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

Utilisez la méthode lookupKey pour obtenir l'ID du projet à partir d'une chaîne de clé.

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"

Annuler la suppression d'une clé API

Si vous supprimez une clé API par erreur, vous pouvez annuler sa suppression (la restaurer) dans les 30 jours suivant l'opération. Passé ce délai, vous ne pouvez plus annuler la suppression de la clé API.

Console

  1. Dans la console Google Cloud, accédez à la page Identifiants.

    Accéder à "Identifiants"

  2. Cliquez sur Restaurer des identifiants supprimés.

  3. Recherchez la clé API supprimée dont vous souhaitez annuler la suppression, puis cliquez sur Restaurer.

    L'annulation de la suppression d'une clé API peut prendre quelques minutes pour se propager. Après la propagation, la clé API dont la suppression a été annulée s'affiche dans la liste des clés API.

gcloud

  1. Obtenez l'ID de la clé dont vous souhaitez annuler la suppression.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la commande gcloud services api-keys list --show-deleted pour lister les clés supprimées de votre projet.

  2. Exécutez la commande gcloud services api-keys undelete pour annuler la suppression d'une clé API.

    gcloud services api-keys undelete KEY_ID

    Remplacez les valeurs suivantes :

    • KEY_ID : ID de la clé dont vous souhaitez annuler la suppression.

REST

  1. Obtenez l'ID de la clé dont vous souhaitez annuler la suppression.

    L'ID est différent du nom à afficher ou de la chaîne de clé. Vous pouvez obtenir l'ID à l'aide de la méthode keys.list, avec le paramètre de requête showDeleted défini sur true. L'ID est listé dans le champ uid de la réponse.

    Remplacez PROJECT_ID par l'ID ou le nom de votre projet 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. Utilisez la méthode undelete pour annuler la suppression de la clé 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"

    Cette requête renvoie une opération de longue durée ; vous devez interroger l'opération pour savoir quand elle est terminée et obtenir l'état de l'opération.

    Remplacez les valeurs suivantes :

    • PROJECT_ID : ID ou nom de votre projet Google Cloud.
    • KEY_ID : ID de la clé que vous souhaitez restreindre.

Interroger des opérations de longue durée

Les méthodes de l'API "API Keys" utilisent des opérations de longue durée. Si vous utilisez l'API REST pour créer et gérer des clés API, un objet d'opération est renvoyé par la requête de méthode initiale. Vous devez utiliser le nom de l'opération pour interroger l'opération de longue durée. Lorsque la requête de longue durée est terminée, l'interrogation de l'opération va renvoyer les données de la requête de longue durée.

Pour interroger une opération de longue durée de l'API "API Keys", vous devez utiliser la méthode operations.get.

Remplacez OPERATION_NAME par le nom d'opération renvoyé par l'opération de longue durée. Exemple : 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 concernant les clés API

Vous pouvez créer jusqu'à 300 clés API par projet. Il s'agit d'une limite du système qui ne peut pas être modifiée par une demande d'augmentation de quota.

Si vous avez besoin de plus de clés d'API, vous devez utiliser plusieurs projets.

Étapes suivantes