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

1. Introduction

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

Points abordés

• Créer des comptes AdWords gérés par un compte administrateur
• Créer des comptes Merchant Center gérés par un multicompte
• Demander l'association d'un compte Merchant Center à un compte AdWords
• Accepter une association Merchant Center en attente dans un compte AdWords

Prérequis

• Un compte administrateur AdWords
• un multicompte Merchant Center ;
• Java 7 ou version ultérieure
• 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 que vous pouvez utiliser.
• 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

Pour cette étape, nous ne allons pas coder, mais configurer des fichiers contenant des jetons d'authentification appropriés pour l'API AdWords et l'API Content 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. 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 à développer: .
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 votre nouvelle clé de compte de service.

Suivez maintenant les instructions pour configurer l'authentification des exemples Shopping avec un compte de service. Autrement dit, une copie de votre clé de compte de service doit se trouver dans le répertoire d'accueil suivant: 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 ne modifiez pas le code (comme dans cette étape), recompilez-le 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 qui s'affiche devrait vous indiquer les identifiants qui ne fonctionnent pas et le fichier à corriger.

Important: Le framework que nous avons fourni suppose que votre compte de service Content API n'est listé que comme utilisateur sur votre compte multi-client. 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 multi-client.

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 créer 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 de code. Recherchez-les pour voir 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 trouver les importations nécessaires.

Définir un nom d'application n'est pas strictement nécessaire, 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 des 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 dernière section 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 aucun 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 dans 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 présenté. C'est pourquoi nous n'affichons que le commentaire (// TODO...) qui indique l'emplacement dans le premier. Par conséquent, 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écifier les paramètres du nouveau compte

Nous allons d'abord créer un objet ManagedCustomer contenant 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. Il s'agit simplement de faire correspondre le compte AdWords que nous allons créer ici avec le compte Merchant Center que nous allons créer plus tard. Nous pourrons ainsi les inspecter visuellement une fois notre solution terminée et nous assurer qu'elle a bien associé les deux.

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 allons ensuite effectuer l'opération à l'aide de la méthode mutate() de l'objet ManagedCustomerService. Cette méthode prend en charge un tableau d'opérations à effectuer, mais nous ne voulons ici 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 seul client, le nouveau compte que nous avons créé. Nous allons récupérer l'ID de ce nouveau compte pour l'utiliser plus tard. Nous allons également l'imprimer pour pouvoir le voir dans la sortie 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'affiche. Accédez au site AdWords pour votre compte administrateur. Vous devriez y voir le nouveau compte.

Remarque:À ce stade, chaque exécution de la solution génère désormais des comptes. Une fois que vous avez exécuté votre solution, vous pouvez résilier les comptes AdWords créés sur le site AdWords. Après tout, notre schéma d'attribution de noms à ces comptes permet de voir facilement ceux qui ont été créés par notre code.

6. Créer un sous-compte Merchant Center

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

Spécifier les paramètres du nouveau sous-compte

Contrairement à l'API AdWords, les sétteurs 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 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, comme nous disposons déjà de l'ID AdWords du nouveau compte géré, nous pouvons l'ajouter à la liste des AdwordsLinks du nouveau sous-compte. Lorsque le nouveau sous-compte sera créé, cette association sera automatiquement demandée et disponible dans l'API AdWords.

Créer le sous-compte

Dans l'API Content, nous appelons la méthode accounts() de l'objet session pour accéder au service Accounts, puis appelons directement la méthode insert() au lieu de configurer un objet d'opération. Cette méthode prend 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 imprimons cette information dans la sortie de notre solution afin de pouvoir l'exécuter, puis de 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 s'afficheront. Accédez à Merchant Center pour votre multicompte pour voir le nouveau sous-compte.

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

7. Accepter l'association depuis le compte AdWords

À l'étape finale, nous avons créé un sous-compte Merchant Center, en demandant l'association à notre nouveau compte AdWords. À 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 le CustomerService. Toutefois, avant de créer le client, nous modifions d'abord notre objet de session AdWords afin que les futures utilisations s'effectuent sur le nouveau compte géré plutôt que sur le compte administrateur. En effet, le compte Merchant Center a demandé à associer le compte géré, et non le 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 l'association demandée

Comme pour la création d'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 souhaitons prendre la liaison de service en attente à un compte MERCHANT_CENTER et la SET à ACTIVE. Pour le paramètre serviceLinkId, nous utiliserons l'ID du compte Merchant Center que nous venons de créer, car il s'agit de l'ID de l'association 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 prend un tableau d'opérations de liaison de services. Cette fois, la méthode renvoie directement une liste de liens de service (éventuellement modifiés). Nous allons donc simplement imprimer le résultat de notre solution en effectuant une boucle sur cette liste. Évidemment, comme nous n'avons spécifié qu'une seule opération, vous ne devriez voir qu'un seul lien s'afficher dans la sortie.

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, vous verrez également une note indiquant que le lien vers le service a été mis à jour pour être actif. Vérifiez dans AdWords et Merchant Center que les comptes sont bien associés.

8. Variations sur un thème

Félicitations, vous avez terminé cet atelier de programmation. Maintenant que vous disposez d'une solution entièrement fonctionnelle, voyons comment la modifier ou l'étendre pour utiliser davantage d'API que vous avez vues dans cet atelier de programmation.

Bonus: Modifier un compte Merchant Center existant pour demander une association AdWords

Dans l'atelier de programmation, nous avons intelligemment 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 modifier 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 modifiez sa configuration pour demander l'association.

Remarque:Vous devez utiliser la méthode Accounts.update ou Accounts.patch. Essayez une version avec chacune d'elles 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 de 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 présentent un exemple d'utilisation d'un intervalle exponentiel entre les tentatives pour relancer des méthodes dans AccountWorkflow.java, qui utilise la méthode retryFailures de BaseWorkflowSample.java.

Bonus: Vérifiez la création de l'association en récupérant les informations des comptes AdWords et Merchant Center

Actuellement, l'application ne considère l'absence d'erreurs dans les appels d'API 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 vous assurer que l'association est bien active.

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

Le monde est à vous

Si vous pensez à d'autres modifications à 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 Java Google Ads.