AdWords- und Merchant Center-Unterkonten erstellen und verknüpfen

1. Einführung

In diesem Codelab lernen Sie die Grundlagen der Arbeit mit der Content API for Shopping und der AdWords API kennen und erstellen eine Anwendung, in der beide verwendet werden. Insbesondere erstellen Sie eine Befehlszeilen-Anwendung, mit der ein AdWords-Konto und ein Merchant Center-Konto erstellt und verknüpft werden.

Aufgaben in diesem Lab

• Hier erfahren Sie, wie Sie AdWords-Konten erstellen, die von einem Verwaltungskonto verwaltet werden.
• Merchant Center-Konten erstellen, die von einem Mehrfachkundenkonto verwaltet werden
• So beantragen Sie eine Verknüpfung zwischen einem Merchant Center-Konto und einem AdWords-Konto.
• So akzeptieren Sie eine ausstehende Merchant Center-Verknüpfung in einem AdWords-Konto.

Voraussetzungen

• Ein Google Ads-Verwaltungskonto
• Sie haben ein Merchant Center-Mehrfachkundenkonto.
• Java 7 oder höher
• Maven
• Beispielcode
• Einen Texteditor (wir empfehlen eine IDE, die Maven-Projekte versteht, z. B. Eclipse oder IntelliJ)

2. Einrichtung

Code herunterladen

Klicken Sie auf den folgenden Link, um den gesamten Code für dieses Codelab herunterzuladen:

Quellcode herunterladen

Entpacken Sie die heruntergeladene ZIP-Datei. Dadurch wird ein Stammordner (shopping-account-linking-master) entpackt, der ein Maven-Projekt mit allen erforderlichen Ressourcen enthält. Die folgenden Unterverzeichnisse sind besonders wichtig:

• src/main/java ist das Stammverzeichnis des Maven-Projekts und enthält ein Code-Skelett, mit dem Sie arbeiten können.
• src/main/java/solution enthält die fertige Lösung.

Erforderliche Pakete installieren und Build ausführen

Wenn Sie eine Maven-kompatible IDE wie Eclipse oder IntelliJ verwenden, können Sie den extrahierten Ordner als Maven-Projekt importieren und das Projekt dann wie gewohnt kompilieren.

Wenn Sie Maven über die Befehlszeile verwenden, können Sie den folgenden Befehl ausführen, um die erforderlichen Pakete abzurufen und das Projekt aus dem Stammverzeichnis des entpackten Projekts (shopping-account-linking-master) zu kompilieren:

mvn compile

3. Authentifizierung einrichten

In diesem Schritt wird kein Code geschrieben, sondern Dateien mit geeigneten Authentifizierungstokens für die AdWords API und die Content API for Shopping eingerichtet.

AdWords API-Authentifizierung einrichten

In diesem Codelab wird dasselbe Anmeldedaten-Ladeverfahren wie in der Clientbibliothek verwendet. Wenn Sie also bereits die Google Ads APIs Client Library for Java mit Ihrem Verwaltungskonto verwendet haben, ist die Einrichtung bereits abgeschlossen. Andernfalls folgen Sie den Schritten 1 bis 3 der Einstiegsanleitung für die Google Ads API-Clientbibliothek für Java.

Authentifizierung für die Content API einrichten

Wenn Sie noch keinen Dienstkontoschlüssel haben, gehen Sie so vor:

1. Rufen Sie das Merchant Center für Ihr Mehrfachkundenkonto auf und wählen Sie im Dreipunkt-Menü die Option Content API aus:
2. Wählen Sie Authentifizierung aus und klicken Sie dann auf die blaue Schaltfläche +:
3. Nachdem Sie die Nutzungsbedingungen für die Google Cloud Platform und Google APIs akzeptiert haben, wird in Ihrem Browser automatisch eine JSON-Datei mit dem neuen Dienstkontoschlüssel heruntergeladen.

Folgen Sie nun der Anleitung zum Einrichten der Authentifizierung für die Shopping-Beispiele mit einem Dienstkonto. Das bedeutet, dass sich eine Kopie Ihres Dienstkontoschlüssels unter dem folgenden Pfad in Ihrem Basisverzeichnis befinden sollte: shopping-samples/content/service-account.json. Sie müssen die Konfiguration der Samples nicht einrichten, es sei denn, Sie möchten die Samples nach Abschluss dieses Codelabs ausprobieren.

Jetzt testen

Da sich die Authentifizierungstokens jetzt an den richtigen Stellen befinden, können Sie die Samples ausführen. Wenn Sie Maven in der Befehlszeile verwenden, führen Sie die folgenden Befehle aus:

mvn compile

Hinweis:Wenn Sie eine der Dateien in src/main/resources ändern, müssen Sie sie neu kompilieren, bevor Sie die Samples ausführen, um die geänderten Ressourcen in das Ziel zu kopieren. Das gilt auch, wenn Sie keine Codeänderungen vornehmen (wie in diesem Schritt).

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

Wenn du eine Fehlermeldung erhältst, dass keine Sitzungsobjekte bereitgestellt wurden, sind deine Authentifizierungstokens vorhanden und funktionieren ordnungsgemäß. Andernfalls sollte die Fehlermeldung angeben, welche Anmeldedaten nicht funktioniert haben und welche Datei korrigiert werden muss.

Wichtig: Bei unserem Framework wird davon ausgegangen, dass Ihr Content API-Dienstkonto nur als Nutzer in Ihrem Mehrkundenkonto aufgeführt ist. Wenn Sie die Fehlermeldung erhalten, dass Ihr Dienstkonto Zugriff auf mehr als ein Konto hat, folgen Sie der Anleitung oben, um einen Dienstkontoschlüssel speziell für Ihr Mehrkundenkonto zu erhalten.

4. Verbindung zu den APIs herstellen

Da Sie jetzt gültige Authentifizierungstokens für die beiden APIs haben, die wir verwenden werden, können wir mit dem Erstellen des eigentlichen Codes beginnen. Wir beginnen mit dem Erstellen von Sitzungsobjekten mit unseren Authentifizierungstokens. In späteren Schritten greifen wir mithilfe dieser Sitzungsobjekte auf die verschiedenen Dienste und Methoden zu, die jede API bietet.

Content API-Sitzungsobjekt erstellen

Um eine Content API-Sitzung zu erstellen, erstellen wir ein ShoppingContent.Builder-Objekt und verwenden es dann, um das entsprechende ShoppingContent-Objekt zu erstellen. Glücklicherweise ist alles, was wir für die erste Funktion benötigen, bereits im Code-Skelett verfügbar. Wir müssen es nur so zusammenstellen:

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();

Hinweis:Die ersten Kommentare in diesem und den folgenden Codebeispielen sind bereits im Code-Skelett enthalten. Suchen Sie nach diesen Markierungen, um zu sehen, wo diese Linien hinzugefügt werden sollten.

Außerdem lassen wir alle erforderlichen Importanweisungen für die AdWords API- und Content API-Klassen aus, die wir in diesen Snippets verwenden. Wenn Sie keine IDE verwenden, die die richtigen Importe automatisch hinzufügen kann, sehen Sie im Code des solution-Pakets nach, ob die erforderlichen Importe vorhanden sind.

Das Festlegen eines Anwendungsnamens ist nicht unbedingt erforderlich. Es zeigt jedoch, wie Sie alle gewünschten Optionen über das ShoppingContent.Builder-Objekt festlegen, bevor Sie die build()-Methode aufrufen.

AdWords API-Sitzungsobjekt erstellen

Ebenso gibt es eine AdWordsSession.Builder-Klasse zum Erstellen von AdWordsSession-Objekten. Der Hauptunterschied besteht darin, dass wir die Konfigurationsoptionen nicht direkt im Builder festlegen, sondern sie mit der Methode fromFile() aus der Datei ads.properties laden, die wir im vorherigen Schritt eingerichtet haben.

SolutionRunner.java

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

Jetzt testen

Wir verwenden dieselben Befehle wie im letzten Abschnitt, um das Maven-Projekt neu zu erstellen und auszuführen, wenn Sie es über die Befehlszeile ausführen:

mvn compile

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

Diesmal sollten Sie keine Fehler erhalten, aber auch keine interessanten Ergebnisse. Wir fügen das hinzu, wenn wir die APIs aufrufen, um die neuen Konten zu erstellen und zu verknüpfen.

5. Neues verwaltetes AdWords-Konto erstellen

Nachdem wir unsere API-Sitzungsobjekte erstellt haben, erstellen wir die Konten, die wir verknüpfen möchten. Wir beginnen mit AdWords und erstellen ein Testkonto in unserem Verwaltungskonto.

Hinweis:Alle Code-Snippets in diesem Abschnitt werden in der angegebenen Reihenfolge an derselben Stelle im Skeletal-Code eingefügt. Aus diesem Grund wird nur der Kommentar (// TODO...)) angezeigt, der angibt, wo sie im ersten Bild platziert werden sollen. Wenn Sie also in diesem und in zukünftigen Schritten Code-Snippets ohne einleitenden Kommentar sehen, fügen Sie sie direkt nach dem vorherigen Snippet ein.

Auf den ManagedCustomerService zugreifen

In der AdWords API greifen wir auf die verschiedenen verfügbaren Dienste zu, indem wir zuerst eine Instanz der Klasse AdWordsServices mithilfe der statischen Methode getInstance() abrufen. Mit dieser Instanz können wir dann über die Methode get() Clients für diese Dienste erstellen. Diese Methode nimmt zwei Argumente entgegen: die Sitzung, für die der Client erstellt werden soll, und die Benutzeroberfläche für den gewünschten Dienst.

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

Hier greifen wir auf den ManagedCustomerService zu, mit dem wir AdWords-Kunden (Konten) über ein bestimmtes Verwaltungskonto verwalten können.

Neue Kontoeinstellungen angeben

Zuerst erstellen wir ein ManagedCustomer-Objekt mit den Einstellungen für unser neues Konto. Wir erstellen ein Testkonto für dieses Codelab und legen als Währung „USD“ und als Zeitzone die Zeitzone der US-Westküste fest.

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

Außerdem erstellen wir eine Zufallszahl, die wir in den Namen des Kontos aufnehmen. So können wir das hier erstellte AdWords-Konto mit dem später erstellten Merchant Center-Konto abgleichen und nach Abschluss der Lösung prüfen, ob die beiden Konten tatsächlich verknüpft sind.

Neues verwaltetes Konto erstellen

Um das neue Konto zu erstellen, verwenden wir ManagedCustomerOperation, um einen ADD-Vorgang anzugeben:

SolutionRunner.java

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

Anschließend führen wir den Vorgang mit der mutate()-Methode des ManagedCustomerService-Objekts aus. Diese Methode nimmt ein Array von Vorgängen an, die ausgeführt werden sollen. Wir möchten hier jedoch nur einen einzelnen Vorgang ausführen. Das Ergebnis der Methode mutate() ist ein Wert, der eine Liste von ManagedCustomers enthält. Hier ist es eine Liste mit einem Kunden, dem neu erstellten Konto. Wir rufen die ID für dieses neue Konto für die spätere Verwendung ab und drucken sie auch aus, damit sie in der Ausgabe unserer Lösung zu sehen ist.

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

Jetzt testen

Versuchen Sie wie zuvor, die Lösung auszuführen. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles richtig funktioniert, sollten Sie weiterhin keine Fehler sehen. Diesmal sehen wir die ID des neuen AdWords-Kontos, das wir erstellt haben. Wenn Sie auf der AdWords nach Ihrem Verwaltungskonto suchen, sollte dort auch das neue Konto aufgeführt sein.

Hinweis:Bei jeder Ausführung der Lösung werden jetzt neue Konten erstellt. Sie können alle erstellten AdWords-Konten über die AdWords kündigen, nachdem Sie die Lösung ausgeführt haben. Schließlich lässt sich anhand unseres Benennungsschemas für diese Konten leicht erkennen, welche von unserem Code erstellt wurden.

6. Neues Merchant Center-Unterkonto erstellen

In diesem Schritt erstellen wir das Merchant Center-Unterkonto, das wir mit dem im letzten Schritt erstellten AdWords-Konto verknüpfen. Anstatt nach dem Erstellen des untergeordneten Kontos separat eine Verknüpfung anzufordern, können wir die Verknüpfung während der Erstellung anfordern, da wir bereits die ID für das entsprechende AdWords-Konto haben.

Einstellungen für das neue Unterkonto festlegen

Im Gegensatz zur AdWords API geben die Setter für die Account-Modellklasse das Objekt zurück. So können wir unsere Aufrufe an das neue Account-Objekt verketten. Die Zufallszahl, die wir bei der Erstellung des AdWords-Kontos generiert haben, wird auch für den Namen des neuen Merchant Center-Kontos verwendet.

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

Wie bereits in der Einführung zu diesem Schritt erwähnt, können wir die AdWords-ID für das neue verwaltete Konto jetzt der Liste der AdwordsLinks für das neue Unterkonto hinzufügen. Wenn das neue Unterkonto erstellt wird, wird diese Verknüpfung automatisch angefordert und ist in der AdWords API verfügbar.

Neues Unterkonto erstellen

In der Content API rufen wir die accounts()-Methode des Sitzungsobjekts auf, um auf den Accounts-Dienst zuzugreifen, und dann die insert()-Methode direkt, anstatt ein Vorgangsobjekt einzurichten. Diese Methode nimmt zwei Argumente an: die ID des Mehrfachkundenkontos, unter dem das neue Unterkonto erstellt werden soll, und das Account-Objekt mit den gewünschten Einstellungen:

SolutionRunner.java

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

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

Die Methode insert() gibt ein Account-Objekt zurück, das die Einstellungen für das neue Unterkonto enthält. Wir überschreiben das ursprüngliche Account-Objekt, da die zurückgegebene Version eine wichtige Information enthält: die ID des neuen Unterkontos. Wir drucken diese in die Ausgabe unserer Lösung aus, damit wir unsere Lösung ausführen und dann prüfen können, ob das neue Unterkonto im Merchant Center vorhanden ist.

Jetzt testen

Versuchen Sie wie zuvor, die Lösung auszuführen. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles richtig funktioniert, sollten Sie weiterhin keine Fehler sehen. Diesmal sehen wir die IDs sowohl für das neue AdWords-Konto als auch für das neue Merchant Center-Konto. Im Merchant Center finden Sie Ihr Mehrfachkundenkonto und dort auch das neue Unterkonto.

Hinweis:Wie bei AdWords werden bei jeder Ausführung der Lösung jetzt neue Merchant Center-Konten generiert. Sie können alle erstellten Unterkonten über das Merchant Center löschen, nachdem Sie die Lösung ausgeführt haben.

7. Verknüpfung aus dem AdWords-Konto akzeptieren

Im letzten Schritt haben wir ein neues Merchant Center-Unterkonto erstellt und gleichzeitig die Verknüpfung mit unserem neuen AdWords-Konto angefordert. In diesem Schritt schließen wir den Vorgang ab, indem wir die angeforderte Verknüpfung über die AdWords API akzeptieren.

Auf den CustomerService zugreifen

Wie zuvor verwenden wir die Klasse AdWordsServices, um einen Client für die CustomerService abzurufen. Bevor wir den Client erstellen, ändern wir jedoch unser AdWords-Sitzungsobjekt, damit zukünftige Verwendungen im neuen verwalteten Konto statt im Verwaltungskonto erfolgen. Schließlich wurde für das Merchant Center-Konto eine Verknüpfung mit dem verwalteten Konto angefordert, nicht mit dem Verwaltungskonto.

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

Angeforderte Verknüpfung angeben

Ähnlich wie beim Erstellen eines neuen AdWords-Kontos erstellen wir ein ServiceLink-Objekt mit den Verknüpfungseinstellungen und dann ein ServiceLinkOperation-Objekt, das die gewünschte Aktion beschreibt. Hier möchten wir die ausstehende Dienstverknüpfung mit einem MERCHANT_CENTER-Konto SET mit ACTIVE verknüpfen. Für die Einstellung serviceLinkId verwenden wir die ID des gerade erstellten Merchant Center-Kontos, da diese für die ID der Dienstverknüpfung in AdWords verwendet wird.

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

Verknüpfung akzeptieren

Abschließend rufen wir die Methode mutateServiceLinks() des CustomerService-Objekts auf, um den Vorgang auszuführen. Wie zuvor wird eine Reihe von Vorgängen für Dienstverknüpfungen verwendet. Diesmal gibt die Methode direkt eine Liste mit (möglicherweise geänderten) Dienstlinks zurück. Wir drucken das Ergebnis unserer Lösung einfach aus, indem wir eine Schleife über diese Liste ausführen. Da wir nur einen einzelnen Vorgang angegeben haben, wird in der Ausgabe natürlich nur ein Link ausgegeben.

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());
}

Jetzt testen

Versuchen Sie wie zuvor, die Lösung auszuführen. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles in Ordnung ist, sollten Sie weiterhin keine Fehler sehen. Diesmal sehen wir auch eine Benachrichtigung, dass der Dienstlink aktualisiert wurde, um aktiv zu sein. Prüfen Sie in AdWords und im Merchant Center, ob die Konten jetzt tatsächlich verknüpft sind.

8. Variationen eines Themas

Herzlichen Glückwunsch, dass Sie das Codelab erfolgreich abgeschlossen haben. Jetzt haben Sie eine voll funktionsfähige Lösung. Sehen wir uns einige Beispiele an, wie Sie sie ändern oder erweitern können, um mehr der APIs zu verwenden, die Sie in diesem Codelab kennengelernt haben.

Zusätzliche Punkte: Vorhandenes Merchant Center-Konto aktualisieren, um eine AdWords-Verknüpfung anzufordern

Im Codelab haben wir das AdWords-Konto zuerst erstellt, damit wir die Informationen daraus verwenden konnten, um die Verknüpfung beim Erstellen des Merchant Center-Kontos anzufordern. Wenn das Merchant Center-Konto bereits vorhanden ist, müssen Sie stattdessen die Konfiguration aktualisieren. Ändern Sie den Code so, dass zuerst das Merchant Center-Konto erstellt wird. Kehren Sie dann nach dem Erstellen des AdWords-Kontos zurück und aktualisieren Sie die Konfiguration, um die Verknüpfung anzufordern.

Hinweis:Verwenden Sie entweder die Methode Accounts.update oder Accounts.patch. Probieren Sie am besten beide Versionen aus, um den Unterschied zu erkennen.

Wichtig: Ein neues Merchant Center-Konto ist möglicherweise nicht sofort nach dem Aufruf von Accounts.insert verfügbar. Bis das neue Konto verfügbar ist, erhalten Sie bei Versuchen, darauf zuzugreifen oder es zu ändern, den HTTP-Fehler 401. In den Shopping-Beispielen finden Sie ein Beispiel für die Verwendung des exponentiellen Backoffs zum Wiederholen von Methoden in AccountWorkflow.java. Dabei wird die retryFailures-Methode aus BaseWorkflowSample.java verwendet.

Zusätzliche Punkte: Überprüfen Sie die Verknüpfung, indem Sie die Informationen zu den AdWords- und Merchant Center-Konten abrufen.

Derzeit betrachtet die Anwendung nur das Fehlen von Fehlern bei API-Aufrufen als Zeichen für einen Erfolg. Erweitern Sie das Beispiel, um die Verknüpfungsinformationen für die neuen Merchant Center- und AdWords-Konten zu prüfen und sicherzustellen, dass die Verknüpfung tatsächlich aktiv ist.

Hinweis:In der Content API solltest du dir die Methode Accounts.get ansehen. In AdWords sollten Sie die Methode getServiceLinks des CustomerServiceInterface-Objekts verwenden.

Die Welt zu Füßen

Wenn dir weitere Änderungen einfallen, kannst du sie ausprobieren. Wenn Sie Referenzcode für Ihre Ideen benötigen, sehen Sie sich die Google Shopping-Beispiele und das Verzeichnis examples in der Java-Clientbibliotheksquelle von Google Ads an.