Créer et associer des sous-comptes AdWords et Merchant Center

1. Introduction

Dans cet atelier de programmation, vous allez découvrir les principes de base de l'utilisation de l'API Content for Shopping et de l'API AdWords, et créer une application qui utilise les deux. Plus précisément, vous allez créer une application en ligne de commande qui créera et associera un compte AdWords et un compte Merchant Center.

Points abordés

• Découvrez comment créer des comptes AdWords gérés par un compte administrateur.
• Découvrez comment créer des comptes Merchant Center gérés par un multicompte.
• Découvrez comment demander l'association d'un compte Merchant Center à un compte AdWords.
• Découvrez comment accepter une association Merchant Center en attente dans un compte AdWords.

Prérequis

• Un compte administrateur AdWords
• Un multicompte Merchant Center
• Java 7+
• Maven
• L'exemple de code
• Un éditeur de texte (un IDE compatible avec les projets Maven, comme Eclipse ou IntelliJ, est recommandé)

2. Configuration

Télécharger le code

Cliquez sur le lien ci-dessous pour télécharger l'ensemble du code de cet atelier de programmation :

Télécharger le code source

Décompressez le fichier ZIP téléchargé. Cela a pour effet de décompresser un dossier racine (shopping-account-linking-master), qui contient un projet Maven ainsi que toutes les ressources dont vous aurez besoin. Les sous-répertoires suivants sont particulièrement importants :

• src/main/java est la racine source du projet Maven et contient un squelette de code dans lequel vous pouvez travailler.
• src/main/java/solution contient la solution finale.

Installer les packages requis et compiler

Si vous utilisez un IDE compatible avec Maven, comme Eclipse ou IntelliJ, vous pouvez importer le dossier extrait en tant que projet Maven, puis compiler le projet normalement.

Si vous utilisez Maven depuis la ligne de commande, vous pouvez exécuter la commande suivante pour récupérer les packages nécessaires et compiler le projet à partir du dossier racine du projet décompressé (shopping-account-linking-master) :

mvn compile

3. Configurer l'authentification

Au cours de cette étape, nous ne coderons pas, mais nous configurerons des fichiers contenant les jetons d'authentification appropriés pour l'API AdWords et la Content API for Shopping.

Configurer l'authentification de l'API AdWords

Cet atelier de programmation utilise le même chargement d'identifiants que la bibliothèque cliente. Par conséquent, si vous avez déjà utilisé la bibliothèque cliente des API Google Ads pour Java avec votre compte administrateur, vous devriez déjà être configuré. Sinon, suivez les étapes 1 à 3 pour commencer à utiliser la bibliothèque cliente des API Google Ads pour Java.

Configurer l'authentification de l'API Content

Si vous ne possédez pas encore de clé de compte de service :

1. Accédez à Merchant Center pour votre multicompte, puis sélectionnez Content API dans le menu à trois points :
2. Sélectionnez Authentification, puis cliquez sur le bouton bleu + :
3. Après avoir accepté les conditions d'utilisation de Google Cloud Platform et des API Google, votre navigateur télécharge automatiquement un fichier JSON contenant la clé de votre nouveau compte de service.

Suivez maintenant les instructions pour configurer l'authentification pour les exemples Shopping avec un compte de service. En d'autres termes, une copie de la clé de votre compte de service doit se trouver au chemin d'accès suivant à partir de votre répertoire d'accueil : shopping-samples/content/service-account.json. Vous n'avez pas besoin de configurer les exemples, sauf si vous souhaitez les essayer après avoir terminé cet atelier de programmation.

Tester les fichiers

Maintenant que vous avez placé les jetons d'authentification aux bons endroits, essayez d'exécuter les exemples. Si vous utilisez Maven sur la ligne de commande, exécutez les commandes suivantes :

mvn compile

Remarque : Si vous modifiez l'un des fichiers de src/main/resources, même si vous n'apportez aucune modification au code (comme dans cette étape), recompilez avant d'exécuter les exemples pour copier vos ressources modifiées vers la cible.

mvn exec:java -Dexec.mainClass="SolutionRunner"

Si vous recevez un message d'erreur indiquant que les objets de session ne sont pas fournis, cela signifie que vos jetons d'authentification sont en place et fonctionnent correctement. Sinon, le message d'erreur que vous recevrez devrait vous indiquer quels identifiants n'ont pas fonctionné et quel fichier corriger.

Important : Le framework que nous avons fourni suppose que votre compte de service de l'API Content n'est répertorié que comme utilisateur de votre compte multiclients. Si vous recevez un message d'erreur indiquant que votre compte de service a accès à plusieurs comptes, suivez les étapes ci-dessus pour obtenir une clé de compte de service spécifique à votre compte multicomptes.

4. Se connecter aux API

Maintenant que vous disposez de jetons d'authentification valides pour les deux API que nous allons utiliser, commençons à remplir le code. Nous allons commencer par créer des objets de session à l'aide de nos jetons d'authentification. Dans les étapes suivantes, nous accéderons aux différents services et méthodes fournis par chaque API à l'aide de ces objets de session.

Créer un objet de session Content API

Pour créer une session Content API, nous allons construire un objet ShoppingContent.Builder, puis l'utiliser pour créer l'objet ShoppingContent approprié. Heureusement, tout ce dont nous avons besoin pour construire le premier est déjà disponible dans le squelette de code. Il nous suffit donc de le rassembler comme suit :

SolutionRunner.java

// TODO(sessions): Create a ShoppingContent object using ShoppingContent.Builder.
contentApiSession =
    new ShoppingContent.Builder(httpTransport, jsonFactory, contentApiCredential)
        .setApplicationName("Linking AdWords and Merchant Center Accounts Codelab")
        .build();

Remarque : Les commentaires initiaux de cet exemple de code et des suivants existent déjà dans le squelette du code. Recherchez-les pour savoir où ces lignes doivent être ajoutées.

Nous omettons également les instructions d'importation nécessaires pour les classes de l'API AdWords et de l'API Content que nous utilisons dans ces extraits. Si vous n'utilisez pas d'IDE capable d'ajouter automatiquement les importations appropriées, veuillez vérifier le code du package solution pour les importations nécessaires.

Il n'est pas strictement nécessaire de définir un nom d'application, mais cela montre comment définir les options souhaitées via l'objet ShoppingContent.Builder avant d'appeler la méthode build().

Créer un objet de session de l'API AdWords

De même, il existe une classe AdWordsSession.Builder pour créer des objets AdWordsSession. La principale différence ici est qu'au lieu de définir les options de configuration directement sur le compilateur, nous utiliserons la méthode fromFile() pour les charger à partir du fichier ads.properties que nous avons configuré à l'étape précédente.

SolutionRunner.java

// TODO(sessions): Create a AdWordsSession object using AdWordsSession.Builder.
adWordsSession =
    new AdWordsSession.Builder()
        .fromFile()
        .withOAuth2Credential(adwordsOAuth2Credential)
        .build();

Tester les fichiers

Nous allons utiliser les mêmes commandes que dans la section précédente pour reconstruire et exécuter le projet Maven, si vous l'exécutez à partir de la ligne de commande :

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Cette fois, vous ne devriez obtenir aucune erreur, mais vous n'obtiendrez pas non plus de résultat intéressant. Nous l'ajouterons lorsque nous appellerons les API pour créer et associer les nouveaux comptes.

5. Créer un compte AdWords géré

Maintenant que nous avons créé nos objets de session d'API, nous allons créer les comptes que nous souhaitons associer. Nous allons commencer par AdWords et créer un compte de test sous notre compte administrateur.

Remarque : Tous les extraits de code de cette section sont ajoutés au même endroit dans le code squelette, dans l'ordre de présentation. C'est pourquoi nous n'afficherons que le commentaire // TODO...) qui indique où les placer dans le premier. Ainsi, dans cette étape et les suivantes, si vous voyez des extraits de code sans commentaire d'introduction, ils se trouvent immédiatement après l'extrait précédent.

Accéder à ManagedCustomerService

Dans l'API AdWords, nous accédons aux différents services disponibles en récupérant d'abord une instance de la classe AdWordsServices à l'aide de la méthode statique getInstance(). À l'aide de cette instance, nous pouvons ensuite créer des clients pour ces services via la méthode get(), qui prend deux arguments : la session pour laquelle créer le client et l'interface du service souhaité.

SolutionRunner.java

// TODO(newAWaccount): Using the ManagedCustomerService, create a new testing AdWords account
// under the given manager account.

AdWordsServicesInterface adWordsServices = AdWordsServices.getInstance();

ManagedCustomerServiceInterface managedCustomerService =
    adWordsServices.get(adWordsSession, ManagedCustomerServiceInterface.class);

Ici, nous accédons à ManagedCustomerService, qui nous permet de gérer les "clients" (comptes) AdWords à partir d'un compte administrateur donné.

Spécifiez les nouveaux paramètres du compte.

Nous allons d'abord créer un objet ManagedCustomer qui contient les paramètres de notre nouveau compte. Nous allons créer un compte de test pour cet atelier de programmation, en définissant sa devise sur USD et son fuseau horaire sur celui de la côte ouest des États-Unis.

SolutionRunner.java

Random rand = new Random();
long run = rand.nextLong();

ManagedCustomer newAdWordsAccount = new ManagedCustomer();
newAdWordsAccount.setName(String.format("AdWords Account Created by Run %d", run));
newAdWordsAccount.setTestAccount(true);
newAdWordsAccount.setCurrencyCode("USD");
newAdWordsAccount.setDateTimeZone("America/Los_Angeles");

Nous créons également un nombre aléatoire que nous incluons dans le nom du compte. Cela nous permettra d'associer le compte Google Ads que nous allons créer ici au compte Merchant Center que nous créerons plus tard. Nous pourrons ainsi les examiner visuellement une fois notre solution terminée et nous assurer qu'ils ont bien été associés.

Créer le compte géré

Pour créer le compte, nous allons utiliser ManagedCustomerOperation pour spécifier une opération ADD :

SolutionRunner.java

ManagedCustomerOperation operation = new ManagedCustomerOperation();
operation.setOperand(newAdWordsAccount);
operation.setOperator(Operator.ADD);

Nous effectuerons ensuite l'opération à l'aide de la méthode mutate() de l'objet ManagedCustomerService. Cette méthode prend un tableau d'opérations à effectuer, mais ici, nous ne voulons effectuer qu'une seule opération. Le résultat de la méthode mutate() est une valeur contenant une liste de ManagedCustomer. Ici, il s'agit d'une liste contenant un client, le nouveau compte que nous avons créé. Nous récupérerons l'ID de ce nouveau compte pour l'utiliser ultérieurement. Nous l'imprimerons également pour qu'il s'affiche dans les résultats de notre solution.

SolutionRunner.java

ManagedCustomerReturnValue result =
    managedCustomerService.mutate(new ManagedCustomerOperation[] {operation});
Long adWordsId = result.getValue()[0].getCustomerId();
System.out.printf("Created new AdWords account %d%n", adWordsId);

Tester les fichiers

Comme précédemment, essayez d'exécuter la solution. Si vous utilisez Maven à partir de la ligne de commande :

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Si tout se passe bien, aucune erreur ne devrait s'afficher. Cette fois, l'ID du nouveau compte AdWords que nous avons créé s'affichera. Consultez le site AdWords pour votre compte administrateur. Le nouveau compte devrait également y figurer.

Remarque : À ce stade, chaque exécution de la solution génère de nouveaux comptes. Vous pouvez résilier tous les comptes AdWords créés sur le site AdWords une fois que vous avez terminé d'exécuter votre solution. Après tout, notre système de dénomination de ces comptes permet de voir facilement ceux qui ont été créés par notre code.

6. Créer un sous-compte Merchant Center

Dans cette étape, nous allons créer le sous-compte Merchant Center que nous associerons au compte AdWords créé à l'étape précédente. Au lieu de demander une association séparément après avoir créé le sous-compte, nous pouvons le faire lors de la création, car nous disposons déjà de l'ID du compte AdWords correspondant.

Spécifiez les paramètres du nouveau sous-compte.

Contrairement à l'API AdWords, les setters de la classe de modèle Account renvoient l'objet. Nous pouvons donc enchaîner nos appels sur le nouvel objet Account. Nous utiliserons également le nombre aléatoire que nous avons généré lors de la création du compte AdWords dans le nom du nouveau compte Merchant Center.

SolutionRunner.java

Account newMcAccount = new Account()
    .setName(String.format("Merchant Center Account Created by Run %d", run))
    .setAdwordsLinks(
        ImmutableList.of(
            new AccountAdwordsLink()
                .setAdwordsId(BigInteger.valueOf(adWordsId))
                .setStatus("active")));

Comme indiqué dans l'introduction de cette étape, nous disposons déjà de l'ID AdWords du nouveau compte géré. Nous pouvons donc l'ajouter dès maintenant à la liste des AdwordsLinks pour le nouveau sous-compte. Lorsque le nouveau sous-compte est créé, cette association est automatiquement demandée et disponible dans l'API AdWords.

Créez le sous-compte.

Dans l'API Content, nous appelons la méthode accounts() de l'objet de session pour accéder au service Accounts, puis nous appelons directement la méthode insert() au lieu de configurer un objet d'opération. Cette méthode accepte deux arguments : l'ID du multicompte sous lequel créer le sous-compte et l'objet Account contenant les paramètres souhaités :

SolutionRunner.java

newMcAccount = contentApiSession.accounts().insert(mcaId, newMcAccount).execute();

System.out.printf("Created new Merchant Center account %s%n", newMcAccount.getId());

La méthode insert() renvoie un objet Account contenant les paramètres du nouveau sous-compte. Nous écrasons notre objet Account d'origine, car la version renvoyée inclut une information importante : l'ID du nouveau sous-compte. Nous l'imprimons dans le résultat de notre solution. Nous pouvons donc exécuter notre solution, puis vérifier que le nouveau sous-compte existe dans Merchant Center.

Tester les fichiers

Comme précédemment, essayez d'exécuter la solution. Si vous utilisez Maven à partir de la ligne de commande :

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Si tout se passe bien, aucune erreur ne devrait s'afficher. Cette fois, les ID du nouveau compte AdWords et du nouveau compte Merchant Center devraient être visibles. Consultez votre multicompte Merchant Center pour y voir le nouveau sous-compte.

Remarque : Comme pour AdWords, chaque exécution de la solution génère désormais de nouveaux comptes Merchant Center. Vous pouvez supprimer les sous-comptes créés dans Merchant Center une fois que vous avez terminé d'exécuter votre solution.

7. Accepter l'association depuis le compte AdWords

Lors de la dernière étape, nous avons créé un sous-compte Merchant Center et demandé à l'associer à notre nouveau compte AdWords. Dans cette étape, nous allons terminer le processus en utilisant l'API AdWords pour accepter l'association demandée.

Accéder à CustomerService

Comme précédemment, nous allons utiliser la classe AdWordsServices pour obtenir un client pour CustomerService. Toutefois, avant de créer le client, nous modifions d'abord notre objet de session AdWords afin que les utilisations futures fonctionnent sur le nouveau compte géré au lieu du compte administrateur. En effet, le compte Merchant Center a demandé à être associé au compte géré, et non au compte administrateur.

SolutionRunner.java

// TODO(acceptLink): Using the mutateServiceLinks method in CustomerService, accept the
// proposed link between the new AdWords account and the new Merchant Center account.

adWordsSession.setClientCustomerId(adWordsId.toString());

CustomerServiceInterface customerService =
    adWordsServices.get(adWordsSession, CustomerServiceInterface.class);

Spécifier le lien demandé

Comme lorsque nous avons créé un compte AdWords, nous allons créer un objet ServiceLink contenant les paramètres d'association, puis un objet ServiceLinkOperation décrivant l'opération souhaitée. Ici, nous voulons associer le service en attente à un compte MERCHANT_CENTER et le SET à ACTIVE. Pour le paramètre serviceLinkId, nous utiliserons l'ID du compte Merchant Center que nous venons de créer, car il est utilisé pour l'ID du lien de service dans AdWords.

SolutionRunner.java

ServiceLink serviceLink = new ServiceLink();
serviceLink.setServiceLinkId(newMcAccount.getId().longValue());
serviceLink.setLinkStatus(ServiceLinkLinkStatus.ACTIVE);
serviceLink.setServiceType(ServiceType.MERCHANT_CENTER);

ServiceLinkOperation op = new ServiceLinkOperation();
op.setOperator(Operator.SET);
op.setOperand(serviceLink);

Accepter l'association

Enfin, nous appellerons la méthode mutateServiceLinks() de l'objet CustomerService pour effectuer l'opération. Comme précédemment, il accepte un tableau d'opérations de liaison de service. Cette fois, la méthode renvoie directement une liste de liens de service (éventuellement modifiés). Nous allons donc simplement afficher le résultat de notre solution en parcourant cette liste. Bien sûr, comme nous n'avons spécifié qu'une seule opération, vous ne vous attendez à ce qu'un seul lien soit affiché dans le résultat.

SolutionRunner.java

ServiceLink[] mutatedServiceLinks =
    customerService.mutateServiceLinks(new ServiceLinkOperation[] {op});
for (ServiceLink mutatedServiceLink : mutatedServiceLinks) {
  System.out.printf(
      "Service link with service link ID %d, type '%s' updated to status: %s.%n",
      mutatedServiceLink.getServiceLinkId(),
      mutatedServiceLink.getServiceType(),
      mutatedServiceLink.getLinkStatus());
}

Tester les fichiers

Comme précédemment, essayez d'exécuter la solution. Si vous utilisez Maven à partir de la ligne de commande :

mvn compile

mvn exec:java -Dexec.mainClass="SolutionRunner"

Si tout se passe bien, aucune erreur ne devrait s'afficher. Cette fois, une note indiquera également que le lien de service a été mis à jour pour être actif. Vérifiez dans AdWords et Merchant Center que les comptes sont bien associés.

8. Variantes sur un thème

Félicitations, vous avez terminé cet atelier de programmation ! Maintenant que vous disposez d'une solution entièrement fonctionnelle, examinons quelques exemples de la manière dont vous pourriez la modifier ou l'étendre pour utiliser davantage d'API que vous avez vues dans cet atelier de programmation.

Pour aller plus loin : mettre à jour un compte Merchant Center existant pour demander une association à AdWords

Dans l'atelier de programmation, nous avons astucieusement créé le compte AdWords en premier afin de pouvoir utiliser ses informations pour demander l'association lors de la création du compte Merchant Center. Toutefois, si le compte Merchant Center existe déjà, vous devrez plutôt mettre à jour sa configuration. Essayez de modifier votre code pour créer d'abord le compte Merchant Center, puis revenez en arrière après avoir créé le compte AdWords et mettez à jour sa configuration pour demander l'association.

Remarque : Vous devez utiliser la méthode Accounts.update ou Accounts.patch. Essayez même une version avec chacun d'eux pour comprendre la différence.

Important : Il est possible qu'un nouveau compte Merchant Center ne soit pas disponible immédiatement après l'appel à Accounts.insert. Tant que le nouveau compte n'est pas disponible, vous recevrez une erreur HTTP 401 lorsque vous tenterez d'y accéder ou de le modifier. Les exemples Shopping contiennent un exemple d'utilisation de l'intervalle exponentiel entre les tentatives pour relancer les méthodes dans AccountWorkflow.java, qui utilise la méthode retryFailures de BaseWorkflowSample.java.

Pour aller plus loin : vérifiez la création de l'association en récupérant les informations sur les comptes AdWords et Merchant Center.

Actuellement, l'application ne considère l'absence d'erreurs dans les appels d'API que comme un signe de réussite. Essayez d'étendre l'exemple pour vérifier les informations d'association des nouveaux comptes Merchant Center et AdWords, et assurez-vous que l'association est bien active.

Remarque : Du côté de Content API, vous devez examiner la méthode Accounts.get. Du côté AdWords, vous devez utiliser la méthode getServiceLinks de l'objet CustomerServiceInterface.

Le monde vous appartient

Si vous pensez à d'autres modifications que vous pourriez apporter, essayez-les ! Si vous avez besoin de code de référence pour vos idées, consultez les exemples Google Shopping et le répertoire examples dans la source de la bibliothèque cliente Google Ads Java.