Configurer l'accès à l'API

Voici comment configurer l'accès à l'API Data Manager avec un SDK ou REST.

Prérequis

Avant de pouvoir utiliser l'API Data, assurez-vous de disposer des éléments suivants :

  1. Un projet Google Cloud.
  2. Un compte Google disposant de l'autorisation serviceusage.services.enable sur votre projet Google Cloud ou d'un rôle incluant cette autorisation. Par exemple, roles/owner et roles/serviceusage.serviceUsageAdmin incluent tous les deux l'autorisation serviceusage.services.enable. Pour vérifier vos autorisations, consultez Afficher l'accès actuel.

Activer l'API

Si vous ne l'avez pas déjà fait, activez l'API Data Manager en cliquant sur Activer l'API Data Manager ou en suivant les instructions pour effectuer cette étape manuellement.

Activer l'API Data Manager

Si vous ne trouvez pas l'API Data Manager ou si l'activation de l'API Data Manager échoue, vérifiez que votre compte Google répond aux conditions préalables.

Configurer l'authentification

Vous pouvez utiliser n'importe quelle méthode d'authentification chez Google, à l'exception des clés API. Nous vous recommandons de consulter la section Choisir la méthode d'authentification adaptée à votre cas d'utilisation pour déterminer l'approche appropriée à votre cas d'utilisation.

Deux méthodes d'authentification courantes sont les comptes utilisateur et les comptes de service :

  • Comptes utilisateur : représentent les personnes qui interagissent directement avec les API et les services Google.
  • Comptes de service : représentent des applications, et non des personnes, en tant qu'utilisateurs. Elles permettent à vos applications de gérer l'authentification et l'autorisation. Par exemple, si une application a besoin d'accéder aux ressources de Google Cloud.

Votre intégration peut utiliser les identifiants par défaut de l'application (ADC) pour trouver automatiquement les identifiants de l'environnement. Vous n'avez donc pas besoin de modifier le code client pour l'authentification.

Choisissez Compte utilisateur ou Emprunt d'identité d'un compte de service pour configurer les identifiants par défaut de l'application :

Voici la procédure à suivre pour vous authentifier avec les identifiants de votre compte utilisateur :

  1. Configurez les paramètres de Google Auth Platform pour votre projet.

    1. Ouvrez la page Branding dans la console Google Cloud.

    2. Sélectionnez votre projet.

    3. Remplissez le formulaire et cliquez sur Créer.

  2. Étant donné que le champ d'application de l'API Data Manager est un champ d'application sensible, les étapes suivantes sont requises :

    1. Accédez aux paramètres Accès aux données de votre projet.

    2. Cliquez sur Ajouter ou supprimer des niveaux d'accès.

    3. Cochez la case en regard de API du gestionnaire de données dans la liste des étendues, puis cliquez sur Mettre à jour.

    4. Cliquez sur Enregistrer.

    5. Accédez à Audience dans la console Google Cloud, puis mettez à jour l'état de publication et le type d'utilisateur. Apprenez-en davantage sur ces paramètres dans Gérer l'audience de l'application.

  3. Cliquez sur Créer un client OAuth2 pour créer un client OAuth2 dans le projet, ou suivez les instructions pour créer un client OAuth2 Desktop.

    Créer un client OAuth2

    Lors de la dernière étape, cliquez sur TÉLÉCHARGER LA CONFIGURATION DU CLIENT et notez l'emplacement de téléchargement que vous avez choisi.

  4. Générez un fichier ADC local en exécutant la commande suivante. Cette commande lance un flux web dans lequel vous êtes invité à vous connecter au compte Google que vous utilisez avec l'API.

    Remplacez PATH_TO_CLIENT_JSON par le nom du fichier JSON que vous avez téléchargé.

    gcloud auth application-default login \
  --scopes="https://www.googleapis.com/auth/datamanager,https://www.googleapis.com/auth/cloud-platform" \
  --client-id-file="PATH_TO_CLIENT_JSON"

  5. Vérifiez que les identifiants sont correctement configurés à l'aide de la commande suivante. En cas de succès, la commande affiche un jeton d'accès sur la console.

    gcloud auth application-default print-access-token

Pour en savoir plus sur l'authentification et les identifiants de votre application, consultez Méthodes d'authentification chez Google et Fonctionnement des identifiants par défaut de l'application.

Configurer l'accès au compte d'exploitation

Accordez à l'adresse e-mail associée à votre compte utilisateur l'accès à Destination.

  • Si vous utilisez un compte Google Ads ou de partenaire de données, suivez les instructions pour ajouter l'adresse e-mail de l'utilisateur au compte.
  • Si vous utilisez un compte Display & Video 360, suivez les instructions pour ajouter l'adresse e-mail de l'utilisateur au compte.

Configurer le SDK correspondant à votre langage de programmation

Sur votre machine locale, installez le SDK de votre choix :

REST

  1. Mettez à jour les espaces réservés dans l'exemple suivant, tels que OPERATING_ACCOUNT_PRODUCT, OPERATING_ACCOUNT_ID et AUDIENCE_ID, avec les valeurs de votre compte et de votre destination.
  2. Remplacez PROJECT_ID par l'ID de votre projet Google Cloud.

  3. Copiez l'exemple dans la ligne de commande pour envoyer la requête.

    Supprimez l'attribut linkedAccount de l'entrée dans destinations si vous n'accédez pas à operatingAccount à l'aide d'un lien produit établi.

    #!/bin/bash

# Uses gcloud to get an access token. If the Application Default
# Credentials aren't for a service account, the command that specifies
# --scopes fails. This sample falls back to the command without the
# --scopes argument.
DATA_MANAGER_ACCESS_TOKEN="$(gcloud auth application-default print-access-token --scopes=https://www.googleapis.com/auth/datamanager || \
  gcloud auth application-default print-access-token)"

# Fetches and prints the scope information for the access token. If you
# get scope-related errors when you send the request in the next step,
# verify that this output includes the Data Manager API scope:
#   https://www.googleapis.com/auth/datamanager
curl https://www.googleapis.com/oauth2/v1/tokeninfo?access_token="${DATA_MANAGER_ACCESS_TOKEN}"

# Sends the request.
curl -X POST "https://datamanager.googleapis.com/v1/audienceMembers:ingest" \
  --header "Authorization: Bearer ${DATA_MANAGER_ACCESS_TOKEN}" \
  --header "x-goog-user-project: PROJECT_ID" \
  --header "Content-Type: application/json" \
  --data @- <<EOF
{
  "destinations": [
    {
      "operatingAccount": {
        "accountType": "OPERATING_ACCOUNT_TYPE",
        "accountId": "OPERATING_ACCOUNT_ID"
      },
      "loginAccount": {
        "accountType": "LOGIN_ACCOUNT_TYPE",
        "accountId": "LOGIN_ACCOUNT_ID"
      },
      "linkedAccount": {
        "accountType": "LINKED_ACCOUNT_TYPE",
        "accountId": "LINKED_ACCOUNT_ID"
      },
      "productDestinationId": "AUDIENCE_ID"
    }
  ],
  "audienceMembers": [
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "07e2f1394b0ea80e2adca010ea8318df697001a005ba7452720edda4b0ce57b3"
          },
          {
            "emailAddress": "1df6b43bc68dd38eca94e6a65b4f466ae537b796c81a526918b40ac4a7b906c7"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "2ef46c4214c3fc1b277a2d976d55194e12b899aa50d721f28da858c7689756e3"
          },
          {
            "emailAddress": "54e410b14fa652a4b49b43aff6eaf92ad680d4d1e5e62ed71b86cd3188385a51"
          },
          {
            "emailAddress": "e8bd3f8da6f5af73bec1ab3fbf7beb47482c4766dfdfc94e6bd89e359c139478"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "05bb62526f091b45d20e243d194766cca8869137421047dc53fa4876d111a6f0"
          },
          {
            "emailAddress": "f1fcde379f31f4d446b76ee8f34860eca2288adc6b6d6c0fdc56d9eee75a2fa5"
          }
        ]
      }
    },
    {
      "userData": {
        "userIdentifiers": [
          {
            "emailAddress": "83a834cc5327bc4dee7c5408988040dc5813c7662611cd93b707aff72bf7d33f"
          },
          {
            "emailAddress": "223ebda6f6889b1494551ba902d9d381daf2f642bae055888e96343d53e9f9c4"
          }
        ]
      }
    }
  ],
  "consent": {
    "adUserData": "CONSENT_GRANTED",
    "adPersonalization": "CONSENT_GRANTED"
  },
  "encoding": "HEX",
  "termsOfService": {
    "customerMatchTermsOfServiceStatus": "ACCEPTED"
  },
  "validateOnly": true
}
EOF

.NET

Installer la bibliothèque cliente

Suivez les instructions du guide d'installation de la bibliothèque cliente.NET pour ajouter une dépendance à la bibliothèque cliente dans votre projet.

Facultatif : Téléchargez la bibliothèque utilitaire et les exemples de code.

  1. Téléchargez et extrayez data-manager-dotnet.tar.gz.

  2. Dans votre projet .NET, déclarez une dépendance ProjectReference sur la bibliothèque utilitaire. Remplacez PATH_TO_UTILITY_LIBRARY par l'emplacement où vous avez extrait le répertoire data-manager-dotnet de data-manager-dotnet.tar.gz.

    <ProjectReference Include="PATH_TO_UTILITY_LIBRARY\Google.Ads.DataManager.Util\src\Google.Ads.DataManager.Util.csproj" />

  3. Pour formater les données, utilisez l'utilitaire Formatter dans votre projet .NET.

  4. Parcourez les exemples de code dans le sous-répertoire samples.

    Passez au répertoire samples et utilisez dotnet run pour obtenir la liste des échantillons disponibles.

    dotnet run

    Passez l'argument --help lors de l'exécution d'un exemple pour imprimer un message d'utilisation avec les paramètres attendus.

    dotnet run -- ingest-audience-members --help

    Pour vous aider à démarrer avec quelques exemples de données, utilisez le fichier à samples/sampledata/audience_members_1.csv.

Java

Installer la bibliothèque cliente

  1. Téléchargez et extrayez google-cloud-ads-datamanager-v1-java.tar.gz.
  2. Accédez au répertoire google-cloud-ads-datamanager-v1-java.

  3. Exécutez la commande suivante pour créer et publier la bibliothèque sur votre dépôt Maven local afin de l'utiliser avec Maven ou Gradle.

    ./gradlew install

  4. Dans votre projet Java, déclarez une dépendance à la bibliothèque API Data Manager.

    Gradle :

    implementation 'com.google.cloud:gapic-google-cloud-ads-datamanager-v1-java:0.1.4'

    Maven:

    <dependency>
  <groupId>com.google.cloud</groupId>
  <artifactId>gapic-google-cloud-ads-datamanager-v1-java</artifactId>
  <version>0.1.4</version>
</dependency>

Facultatif : Téléchargez la bibliothèque utilitaire et les exemples de code.

  1. Clonez le dépôt GitHub.

    git clone https://github.com/googleads/data-manager-java.git

  2. Accédez au répertoire data-manager-java.

  3. Compilez et publiez la bibliothèque utilitaire sur votre dépôt Maven local.

    ./gradlew data-manager-util:install

  4. Dans votre projet Java, déclarez une dépendance à la bibliothèque utilitaire.

    Gradle :

    implementation 'com.google.api-ads:data-manager-util:0.1.0'

    Maven:

    <dependency>
   <groupId>com.google.api-ads</groupId>
   <artifactId>data-manager-util</artifactId>
   <version>0.1.0</version>
</dependency>

  5. Pour formater et chiffrer les données, utilisez les utilitaires UserDataFormatter et Encrypter dans votre projet Java.

  6. Parcourez les exemples de code dans le sous-répertoire data-manager-samples ou sur GitHub. Pour exécuter un exemple à partir de la ligne de commande, utilisez la tâche Gradle run.

    Par exemple, la commande suivante exécute l'exemple IngestAudienceMembers et affiche un message d'utilisation :

    ./gradlew data-manager-samples:run \
   --args='IngestAudienceMembers --help'

    Pour vous aider à démarrer avec quelques exemples de données, utilisez le fichier à data-manager-samples/src/main/resources/sampledata/audience_members_1.csv.

Node.js

Installer la bibliothèque cliente

  1. Téléchargez et extrayez ads-datamanager-v1-nodejs.tar.gz.
  2. Accédez au répertoire ads-datamanager-v1-nodejs.

  3. Exécutez la commande suivante pour compiler et empaqueter la bibliothèque cliente dans un fichier .tgz à utiliser avec npm.

    npm pack

    La commande génère une archive nommée google-cloud-datamanager-0.1.4.tgz. Notez l'emplacement du fichier pour pouvoir l'utiliser lors des étapes suivantes.

  4. Dans votre projet Node.js, déclarez une dépendance sur la bibliothèque cliente de l'API Data Manager en ajoutant une entrée dependencies pour le chemin d'accès complet et le nom de fichier du fichier google-cloud-datamanager-0.1.4.tgz.

    {
   "dependencies": {
      ...
      "@google-cloud/datamanager": "file:PATH_TO_CLIENT_LIBRARY/google-cloud-datamanager-0.1.4.tgz",
      ...
   }
}

Facultatif : Obtenez la bibliothèque d'utilitaires et les exemples de code.

  1. Téléchargez et extrayez data-manager-node.tar.gz.
  2. Accédez au répertoire data-manager-node.

  3. Accédez au répertoire util.

    cd util

  4. Exécutez la commande suivante pour compiler et empaqueter la bibliothèque d'utilitaires dans un fichier .tgz à utiliser avec npm.

    npm pack

    La commande génère une archive nommée google-ads-datamanager-util-0.1.0.tgz. Notez l'emplacement du fichier pour pouvoir l'utiliser lors des étapes suivantes.

  5. Dans votre projet Node.js, déclarez une dépendance sur la bibliothèque utilitaire de l'API Data Manager en ajoutant une entrée dependencies pour le chemin d'accès complet et le nom de fichier du fichier google-ads-datamanager-util-0.1.0.tgz.

    {
   "dependencies": {
      ...
      "@google-ads/data-manager-util": "file:PATH_TO_UTILITY_LIBRARY/google-ads-datamanager-util-0.1.0.tgz",
      ...
   }
}

    Pour mettre en forme les données, utilisez l'utilitaire UserDataFormatter dans votre projet Node.js.

  6. Parcourez les exemples de code dans le sous-répertoire samples. Exécutez les exemples en procédant comme suit :

    1. Copiez le fichier google-cloud-datamanager-0.1.4.tgz dans le répertoire parent du répertoire data-manager-node.

    2. Accédez au répertoire samples sous data-manager-node.

    3. Exécutez la commande suivante pour compiler les exemples.

      npm run compile

    4. Exécutez les exemples en transmettant les arguments requis. Passez l'argument --help lors de l'exécution d'un exemple pour imprimer un message d'utilisation avec les paramètres attendus.

      Par exemple, la commande suivante exécute l'exemple ingest_audience_members et affiche une instruction d'utilisation :

      npx ts-node audiences/ingest_audience_members.ts --help

    Pour vous aider à vous lancer avec des exemples de données, utilisez le fichier samples/sampledata/audience_members_1.csv.

PHP

Installer la bibliothèque cliente

  1. Téléchargez et extrayez google-cloud-ads-datamanager-v1-php.tar.gz.
  2. Accédez au répertoire google-cloud-ads-datamanager-v1-php.

  3. Exécutez la commande suivante pour résoudre les dépendances de la bibliothèque :

    composer update --prefer-dist

  4. Dans le fichier composer.json de votre projet PHP sur le même hôte, déclarez une dépendance à la bibliothèque Data Manager API en suivant les étapes suivantes :

    1. Ajoutez une section repositories qui pointe vers l'emplacement du répertoire google-cloud-ads-datamanager-v1-php.

      "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_CLIENT_LIBRARY"
   }
]

    2. Déclarez une dépendance sur la bibliothèque de l'API Data Manager.

      "require": {
   "googleads/data-manager": "0.1.4"
}

Facultatif : Téléchargez la bibliothèque utilitaire et les exemples de code.

  1. Téléchargez et extrayez data-manager-php.tar.gz.
  2. Accédez au répertoire data-manager-php.

  3. Exécutez la commande suivante pour résoudre les dépendances de la bibliothèque :

    composer update --prefer-dist

  4. Dans le fichier composer.json de votre projet PHP sur le même hôte, déclarez une dépendance à la bibliothèque utilitaire en suivant les étapes suivantes :

    1. Ajoutez une entrée dans la section repositories qui pointe vers l'emplacement du répertoire data-manager-php.

      "repositories" : [
   {
      "type" : "path",
      "url" : "PATH_TO_UTILITY_LIBRARY"
   }
]

    2. Déclarez une dépendance à la bibliothèque utilitaire.

      "require": {
   "googleads/data-manager-util": "@dev"
}

    Pour formater les données, utilisez l'utilitaire Formatter dans votre projet PHP.

  5. Parcourez les exemples de code dans le sous-répertoire samples. Exécutez les échantillons en suivant les étapes suivantes :

    1. Accédez au répertoire samples.

    2. Définissez la variable d'environnement DATA_MANAGER_PHP_LIB sur le chemin d'accès à l'emplacement où vous avez extrait la bibliothèque cliente.

      export DATA_MANAGER_PHP_LIB="PATH_TO_CLIENT_LIBRARY"

    3. Exécutez la commande suivante pour résoudre les dépendances de la bibliothèque :

      composer update --prefer-dist

    4. Exécutez les exemples en passant les arguments requis. Passez l'argument --help lors de l'exécution d'un exemple pour imprimer un message d'utilisation avec les paramètres attendus.

    Pour vous aider à démarrer avec quelques exemples de données, utilisez le fichier à samples/sampledata/audience_members_1.csv.

Python

Installer la bibliothèque cliente

Suivez les instructions du guide d'installation de la bibliothèque cliente Python pour ajouter une dépendance à la bibliothèque cliente google-ads-datamanager dans votre projet.

Facultatif : Téléchargez la bibliothèque utilitaire et les exemples de code.

  1. Téléchargez et extrayez data-manager-python.tar.gz.
  2. Accédez au répertoire data-manager-python.

  3. Pour installer la bibliothèque utilitaire dans votre environnement Python, exécutez la commande suivante :

    pip install .

  4. Dans votre projet Python, déclarez une dépendance à la bibliothèque utilitaire. Par exemple, si vous utilisez un fichier requirements.txt dans votre projet, ajoutez la ligne suivante au fichier :

    google-ads-data-manager-util=0.2.0

  5. Pour mettre en forme et chiffrer les données, utilisez les utilitaires Formatter et Encrypter dans votre projet Python.

  6. Parcourez les exemples de code dans le sous-répertoire samples. Pour exécuter les exemples, installez les dépendances nécessaires :

    pip install .[samples]

    Passez l'argument --help lors de l'exécution d'un exemple pour imprimer un message d'utilisation avec les paramètres attendus.

    Pour vous aider à démarrer avec quelques exemples de données, utilisez le fichier à samples/sampledata/audience_members_1.csv.

Ruby

Installer la bibliothèque cliente

Suivez les instructions dans leguide d'installation de la bibliothèque cliente Ruby pour ajouter une dépendance à la bibliothèque cliente de votre projet.

Étapes suivantes

  • Apprenez-en davantage sur l'envoi de données d'audience .
  • Apprenez-en davantage sur l'envoi d'événements .
  • Consultez la documentation de référence REST ou RPC.