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

1. Introduction

Dans cet atelier de programmation, vous allez découvrir les bases de l'utilisation de Content API for Shopping et de l'API AdWords, et créer une application qui les utilise. Plus précisément, vous allez concevoir une application de ligne de commande qui permet de créer et d'associer 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 à un compte 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 qui comprend 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é. Cette opération 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 avez 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 à partir de 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 non empaqueté (shopping-account-linking-master):

mvn compile

3. Configurer l'authentification

Lors de cette étape, nous n'allons pas coder, mais configurer des fichiers contenant les jetons d'authentification appropriés pour l'API AdWords et 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 ne devriez pas avoir de problème. Sinon, suivez les étapes 1 à 3 pour démarrer avec la bibliothèque cliente des API Google Ads pour Java.

Configurer l'authentification Content API

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

1. Accédez au compte Merchant Center de votre multicompte, puis sélectionnez Content API dans le menu à développer:
2. Sélectionnez Authentication (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 pour les exemples Shopping avec un compte de service. Autrement dit, une copie de la clé de votre compte de service doit se trouver dans le chemin d'accès suivant depuis votre répertoire d'accueil: shopping-samples/content/service-account.json. Vous n'avez pas besoin de définir la configuration des exemples, sauf si vous souhaitez tester les exemples une fois cet atelier de programmation terminé.

Tester

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

mvn compile

Remarque:Si vous modifiez l'un des fichiers dans 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 sur 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 devrait vous indiquer les identifiants qui n'ont pas fonctionné et le fichier à corriger.

Important: Le framework que nous fournissons suppose que votre compte de service Content API n'est répertorié qu'en tant qu'utilisateur dans votre multicompte. Si vous recevez un message d'erreur indiquant que votre compte de service a accès à plusieurs comptes, suivez les étapes ci-dessus afin d'obtenir une clé de compte de service spécifique à votre multicompte.

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, vous devez 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 l'assembler 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 exemples suivants existent déjà dans le squelette de code. Recherchez-les pour voir où ces lignes doivent être ajoutées.

En outre, nous ignorons les instructions d'importation nécessaires pour l'API AdWords et les classes de l'API Content que nous utilisons dans ces extraits. Si vous n'utilisez pas un 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 est qu'au lieu de définir les options de configuration directement dans 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

Nous allons utiliser les mêmes commandes que dans la section précédente pour recompiler 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 ajouterons cela 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 API, nous allons passer en revue et créer les comptes que nous voulons associer. Commençons par AdWords, puis créons 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 de squelette, dans l'ordre présenté. C'est pourquoi nous n'afficherons que le commentaire (// TODO...), qui indique où les placer dans le premier élément. Ainsi, au cours de cette étape et des suivantes, si vous voyez des extraits de code sans commentaire d'introduction, ils sont placés 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 accepte 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 au service ManagedCustomerService, qui nous permet de gérer les "clients" AdWords (comptes) d'un compte administrateur donné.

Spécifier les nouveaux paramètres du compte

Tout d'abord, nous allons créer un objet ManagedCustomer contenant les paramètres de notre nouveau compte. Pour cet atelier de programmation, nous allons créer un compte de test en définissant le dollar américain comme devise et le même fuseau horaire que 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'établir une correspondance entre le compte AdWords que nous allons créer ici et le compte Merchant Center que nous créerons ultérieurement. Nous pourrons ainsi les examiner visuellement une fois que nous aurons terminé et vérifier qu'il 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);

Ensuite, nous effectuerons l'opération à l'aide de la méthode mutate() de l'objet ManagedCustomerService. Cette méthode nécessite un tableau d'opérations à effectuer, mais dans le cas présent, nous ne voulons effectuer qu'une seule opération. Le résultat de la méthode mutate() est une valeur contenant une liste d'éléments ManagedCustomer. ici, il s'agira d'une liste contenant un client, le nouveau compte que nous avons créé. Nous allons récupérer l'ID de ce nouveau compte pour une utilisation ultérieure et l'imprimer pour qu'il apparaisse dans le résultat 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

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 déroule comme prévu, aucune erreur ne devrait apparaître et l'ID du nouveau compte AdWords que nous avons créé s'affiche cette fois-ci. Sur le site AdWords associé à votre compte administrateur, vous devriez y trouver votre nouveau compte.

Remarque:À ce stade, de nouveaux comptes seront générés à chaque exécution de la solution. Une fois que vous avez terminé l'exécution de votre solution, vous pouvez désactiver les comptes AdWords créés sur le site AdWords. Après tout, notre schéma d'attribution de noms permet d'identifier facilement ceux qui ont été créés par notre code.

6. Créer un sous-compte Merchant Center

Lors de 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 demander l'association 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 setters de la classe de modèle Account renvoient l'objet. Cela nous permet d'enchaîner nos appels vers 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, étant donné que nous disposons déjà de l'ID AdWords du nouveau compte géré, nous pouvons dès à présent l'ajouter à la liste AdwordsLinks du nouveau sous-compte. Une fois le sous-compte créé, cette association est automatiquement demandée et disponible dans l'API AdWords.

Créer le sous-compte

Dans Content API, 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 utilise deux arguments: l'ID du multicompte sous lequel créer le sous-compte et l'objet Account qui contient 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 remplaçons notre objet Account d'origine, car la version renvoyée comprend une information importante: l'ID du nouveau sous-compte. Nous imprimons cela dans le résultat de notre solution afin de l'exécuter, puis de vérifier que le nouveau sous-compte existe dans Merchant Center.

Tester

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 déroule comme prévu, aucune erreur ne devrait apparaître. Cette fois-ci, nous affichons les identifiants des nouveaux comptes AdWords et Merchant Center. Accédez à Merchant Center pour votre multicompte afin d'y afficher le nouveau sous-compte.

Remarque:Comme pour AdWords, de nouveaux comptes Merchant Center seront désormais générés à chaque exécution de la solution. Une fois la solution exécutée, vous pourrez supprimer tous les sous-comptes créés via Merchant Center.

7. Accepter l'association à partir du compte AdWords

Lors de la dernière étape, nous avons créé un sous-compte Merchant Center en demandant à l'associer au nouveau compte AdWords en même temps. Lors de 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 afin d'obtenir un client pour CustomerService. Toutefois, avant de créer le client, nous devons d'abord modifier l'objet de session AdWords afin que les futurs utilisateurs se fassent sur le nouveau compte géré, et non sur le compte administrateur. Après tout, 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 lors de la création d'un compte AdWords, nous créons un objet ServiceLink contenant les paramètres du lien, puis un objet ServiceLinkOperation qui décrit l'opération souhaitée. Ici, nous voulons transférer le lien de service en attente vers un compte MERCHANT_CENTER et le SET vers 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 de l'association de services 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 le lien

Enfin, nous allons appeler la méthode mutateServiceLinks() de l'objet CustomerService pour effectuer l'opération. Comme précédemment, un ensemble d'opérations de liaison de service est nécessaire. Cette fois, la méthode renvoie directement une liste de liens de service (éventuellement modifiés). Nous allons donc afficher le résultat de notre solution en effectuant une boucle sur cette liste. Bien entendu, étant donné que nous n'avons spécifié qu'une seule opération, vous vous attendez à ce qu'un seul lien s'affiche 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

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 déroule comme prévu, vous ne devriez toujours voir aucune erreur et cette fois, vous verrez également une note indiquant que le lien du service a été mis à jour et est désormais actif. Consultez AdWords et Merchant Center, puis assurez-vous que les comptes sont bien associés.

8. Variantes sur un thème

Bravo ! Vous avez terminé cet atelier de programmation. Maintenant que vous disposez d'une solution entièrement fonctionnelle, examinons quelques exemples de la façon dont vous pouvez la modifier ou l'étendre afin d'utiliser davantage des API que vous avez vues dans cet atelier de programmation.

Crédit supplémentaire: mettre à jour un compte Merchant Center existant pour demander une association à AdWords

Dans cet atelier de programmation, nous avons d'abord astucieusement créé le compte AdWords 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 mettre à jour sa configuration. Essayez d'abord de modifier votre code pour créer le compte Merchant Center, puis revenez après avoir créé le compte AdWords et mettez à jour sa configuration pour demander l'association.

Remarque:Nous vous conseillons d'utiliser la méthode Accounts.update ou Accounts.patch. Vous pouvez essayer une version avec chacune d'elles pour comprendre la différence.

Important: Il est possible que vous ne puissiez pas créer de compte Merchant Center immédiatement après avoir appelé le Accounts.insert. Tant que le nouveau compte n'est pas disponible, vous obtenez une erreur HTTP 401 à chaque tentative d'accès ou de modification. Les exemples Shopping présentent un exemple d'intervalle exponentiel entre les tentatives pour relancer les méthodes dans AccountWorkflow.java, qui utilise la méthode retryFailures de BaseWorkflowSample.java.

Crédit supplémentaire: vérifiez que l'association a bien été créée 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 que comme un signe de réussite. Développez l'exemple en vérifiant les informations sur l'association pour les nouveaux comptes Merchant Center et AdWords, et vérifiez que l'association est bien active.

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

Le monde est à vous

Si vous pensez à d'autres changements 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 le code source de la bibliothèque cliente Google Ads pour Java.