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

1. Einführung

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

Lerninhalte

• Erstellen von Google Ads-Konten, die von einem Verwaltungskonto verwaltet werden
• Erstellen von Merchant Center-Konten, die von einem Mehrfachkundenkonto verwaltet werden
• Anfordern einer Verknüpfung von einem Merchant Center-Konto zu einem Google Ads-Konto
• Akzeptieren einer ausstehenden Merchant Center-Verknüpfung in einem Google Ads-Konto

Voraussetzungen

• Ein Google Ads-Verwaltungskonto
• Ein Merchant Center-Mehrfachkundenkonto
• Java 7 oder höher
• Maven
• Der Beispielcode
• Ein Texteditor (empfohlen wird 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 sowie alle erforderlichen Ressourcen enthält. Die folgenden Unterverzeichnisse sind besonders wichtig:

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

Erforderliche Pakete installieren und erstellen

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

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

mvn compile

3. Authentifizierung einrichten

In diesem Schritt schreiben wir keinen Code, sondern richten Dateien ein, die die entsprechenden Authentifizierungstokens für die Google Ads API und die Content API for Shopping enthalten.

Authentifizierung für die Google Ads API einrichten

In diesem Codelab wird dieselbe Methode zum Laden von Anmeldedaten wie in der Clientbibliothek verwendet. Wenn Sie die Google Ads APIs-Clientbibliothek für Java bereits mit Ihrem Verwaltungskonto verwendet haben, sollten Sie also bereits alles eingerichtet haben. Andernfalls folgen Sie der Anleitung unter Erste Schritte mit der Google Ads APIs-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 Überlaufmenü 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 die Google APIs akzeptiert haben, wird in Ihrem Browser automatisch eine JSON-Datei mit Ihrem neuen Dienstkontoschlüssel heruntergeladen.

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

Testen

Nachdem Sie die Authentifizierungstokens an den richtigen Stellen platziert haben, können Sie die Beispiele ausführen. Wenn Sie Maven über die Befehlszeile verwenden, führen Sie die folgenden Befehle aus:

mvn compile

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

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

Wenn Sie eine Fehlermeldung erhalten, dass keine Sitzungsobjekte bereitgestellt wurden, sind Ihre Authentifizierungstokens vorhanden und funktionieren richtig. Andernfalls sollte die Fehlermeldung Ihnen mitteilen, welche Anmeldedaten nicht funktioniert haben und welche Datei Sie korrigieren müssen.

Wichtig: Das von uns bereitgestellte Framework geht davon aus, dass Ihr Dienstkonto für die Content API nur als Nutzer in Ihrem Mehrfachkundenkonto aufgeführt ist. Wenn Sie eine Fehlermeldung erhalten, dass Ihr Dienstkonto Zugriff auf mehr als ein Konto hat, folgen Sie der obigen Anleitung, um einen Dienstkontoschlüssel speziell für Ihr Mehrfachkundenkonto zu erhalten.

4. Verbindung zu den APIs herstellen

Nachdem Sie nun gültige Authentifizierungstokens für die beiden APIs haben, die wir verwenden werden, können wir mit dem Ausfüllen des eigentlichen Codes beginnen. Zuerst erstellen wir Sitzungsobjekte mit unseren Authentifizierungstokens. In späteren Schritten greifen wir mit diesen Sitzungsobjekten auf die verschiedenen Dienste und Methoden zu, die jede API bietet.

Sitzungsobjekt für die Content API erstellen

Um eine Sitzung für die Content API 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 zum Erstellen des ersten Objekts benötigen, bereits im Code-Skelett vorhanden. Wir müssen es nur so zusammenfügen:

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 vorhanden. Suchen Sie nach ihnen, um zu sehen, wo diese Zeilen hinzugefügt werden sollen.

Außerdem lassen wir alle erforderlichen Importanweisungen für die Google Ads API- und Content API-Klassen weg, die wir in diesen Snippets verwenden. Wenn Sie keine IDE verwenden, die die richtigen Importe automatisch hinzufügen kann, sehen Sie im Paket solution nach, welche Importe erforderlich sind.

Das Festlegen eines Anwendungsnamens ist nicht unbedingt erforderlich, zeigt aber, wie Sie beliebige Optionen über das ShoppingContent.Builder-Objekt festlegen können, bevor Sie die Methode build() aufrufen.

Sitzungsobjekt für die Google Ads API erstellen

Ähnlich 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 die Methode fromFile() verwenden, um sie aus der Datei ads.properties zu 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();

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"

Dieses Mal sollten keine Fehler auftreten, aber Sie erhalten auch keine interessante Ausgabe. Das fügen wir hinzu, wenn wir die APIs aufrufen, um die neuen Konten zu erstellen und zu verknüpfen.

5. Neues verwaltetes Google Ads-Konto erstellen

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

Hinweis:Alle Code-Snippets in diesem Abschnitt werden an derselben Stelle im Skelettcode in der angegebenen Reihenfolge hinzugefügt. Aus diesem Grund zeigen wir nur den Kommentar (// TODO...) der angibt, wo sie platziert werden sollen. Wenn Sie in diesem und zukünftigen Schritten Code-Snippets ohne einleitenden Kommentar sehen, werden sie direkt nach dem vorherigen Snippet platziert.

Auf den ManagedCustomerService zugreifen

In der Google Ads API greifen wir auf die verschiedenen verfügbaren Dienste zu, indem wir zuerst eine Instanz der Klasse AdWordsServices mit der statischen Methode getInstance() abrufen. Mit dieser Instanz können wir dann mit der Methode get() Clients für diese Dienste erstellen. Diese Methode verwendet zwei Argumente: die Sitzung, für die der Client erstellt werden soll, und die Schnittstelle 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 Google Ads-Kunden (Konten) über ein bestimmtes Verwaltungskonto verwalten können.

Einstellungen für das neue Konto angeben

Zuerst erstellen wir ein ManagedCustomer-Objekt, das die Einstellungen für unser neues Konto enthält. Für dieses Codelab erstellen wir ein Testkonto, dessen Währung auf USD und dessen Zeitzone auf die der US-Westküste festgelegt ist.

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 Google Ads-Konto, das wir hier erstellen, mit dem Merchant Center-Konto abgleichen, das wir später erstellen. So können wir sie visuell prüfen, sobald unsere Lösung fertig ist, und sicherstellen, dass die beiden Konten tatsächlich verknüpft wurden.

Neues verwaltetes Konto erstellen

Um das neue Konto tatsächlich 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 Methode mutate() des Objekts ManagedCustomerService aus. Diese Methode verwendet ein Array von Vorgängen, die ausgeführt werden sollen. Hier möchten wir jedoch nur einen einzelnen Vorgang ausführen. Das Ergebnis der Methode mutate() ist ein Wert, der eine Liste von ManagedCustomer-Objekten enthält. Hier ist es eine Liste mit einem Kunden, dem neuen Konto, das wir erstellt haben. Wir rufen die ID für dieses neue Konto zur späteren Verwendung ab und geben sie auch aus, damit sie als Teil der Ausgabe unserer Lösung angezeigt wird.

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

Testen

Führen Sie die Lösung wie zuvor aus. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles gut geht, sollten keine Fehler auftreten und dieses Mal wird die ID des neuen Google Ads-Kontos angezeigt, das wir erstellt haben. Prüfen Sie die AdWords-Website für Ihr Verwaltungskonto. Dort sollte das neue Konto ebenfalls aufgeführt sein.

Hinweis:Bei jeder Ausführung der Lösung werden jetzt neue Konten erstellt. Sie können alle erstellten Google Ads-Konten über die AdWords-Website kündigen, nachdem Sie die Lösung ausgeführt haben. Unser Benennungsschema für diese Konten macht es einfach zu 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 Google Ads-Konto verknüpfen, das wir im letzten Schritt erstellt haben. Anstatt nach dem Erstellen des Unterkontos 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 Google Ads-Konto haben.

Einstellungen für das neue Unterkonto angeben

Im Gegensatz zur Google Ads API geben die Setter für die Modellklasse Account das Objekt zurück, sodass wir unsere Aufrufe an sie im neuen Account-Objekt verketten können. Wir verwenden die Zufallszahl, die wir bei der Erstellung des Google Ads-Kontos generiert haben, auch im Namen des neuen Merchant Center-Kontos.

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 in der Einführung zu diesem Schritt erwähnt, können wir die Google Ads-ID für das neue verwaltete Konto jetzt der Liste der AdwordsLinks für das neue Unterkonto hinzufügen, da wir sie bereits haben. Wenn das neue Unterkonto erstellt wird, wird diese Verknüpfung automatisch angefordert und ist in der Google Ads API verfügbar.

Neues Unterkonto erstellen

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

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 unser ursprüngliches Account-Objekt, da die zurückgegebene Version eine wichtige Information enthält: die ID des neuen Unterkontos. Wir geben diese in der 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.

Testen

Führen Sie die Lösung wie zuvor aus. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles gut geht, sollten keine Fehler auftreten und dieses Mal werden die IDs für das neue Google Ads-Konto und das neue Merchant Center-Konto angezeigt. Prüfen Sie das Merchant Center für Ihr Mehrfachkundenkonto. Dort sollte das neue Unterkonto aufgeführt sein.

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

7. Verknüpfung vom Google Ads-Konto akzeptieren

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

Auf den CustomerService zugreifen

Wie zuvor verwenden wir die Klasse AdWordsServices, um einen Client für den CustomerService zu erhalten. Bevor wir den Client erstellen, ändern wir jedoch zuerst unser Google Ads-Sitzungsobjekt, sodass zukünftige Verwendungen für das neue verwaltete Konto und nicht für das Verwaltungskonto erfolgen. Schließlich wurde für das Merchant Center-Konto eine Verknüpfung zum verwalteten Konto angefordert, nicht zum 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);

Die angeforderte Verknüpfung angeben

Wie beim Erstellen eines neuen Google Ads-Kontos erstellen wir ein ServiceLink Objekt, das die Verknüpfungseinstellungen enthält, und dann ein ServiceLinkOperation Objekt, das den gewünschten Vorgang beschreibt. Hier möchten wir die ausstehende Dienstverknüpfung zu einem MERCHANT_CENTER-Konto verwenden und sie auf ACTIVE SET setzen. Für die Einstellung serviceLinkId verwenden wir die ID des Merchant Center-Kontos, das wir gerade erstellt haben, da diese für die ID der Dienstverknüpfung in Google Ads 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 ein Array von Dienstverknüpfungsvorgängen verwendet. Dieses Mal gibt die Methode direkt eine Liste von (möglicherweise geänderten) Dienstverknüpfungen zurück. Wir geben das Ergebnis unserer Lösung also einfach aus, indem wir diese Liste durchlaufen. Da wir nur einen einzelnen Vorgang angegeben haben, wird in der Ausgabe natürlich nur eine einzelne Verknüpfung angezeigt.

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

Testen

Führen Sie die Lösung wie zuvor aus. Wenn Sie Maven über die Befehlszeile verwenden:

mvn compile

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

Wenn alles gut geht, sollten keine Fehler auftreten und dieses Mal wird auch eine Meldung angezeigt, dass die Dienstverknüpfung auf „Aktiv“ aktualisiert wurde. Prüfen Sie AdWords und das Merchant Center und vergewissern Sie sich, dass die Konten jetzt tatsächlich verknüpft sind.

8. Variationen

Herzlichen Glückwunsch, dass Sie das Codelab durchgearbeitet haben. Nachdem Sie nun eine voll funktionsfähige Lösung haben, sehen wir uns einige Beispiele an, wie Sie sie ändern oder erweitern können, um weitere APIs zu verwenden, die Sie in diesem Codelab kennengelernt haben.

Zusatzaufgabe: Vorhandenes Merchant Center-Konto aktualisieren, um eine Google Ads-Verknüpfung anzufordern

In diesem Codelab haben wir zuerst das Google Ads-Konto erstellt, damit wir seine Informationen verwenden konnten, um die Verknüpfung beim Erstellen des Merchant Center-Kontos anzufordern. Wenn das Merchant Center-Konto jedoch bereits vorhanden ist, müssen Sie stattdessen seine Konfiguration aktualisieren. Ändern Sie Ihren Code so, dass zuerst das Merchant Center-Konto erstellt wird. Aktualisieren Sie dann nach dem Erstellen des Google Ads-Kontos dessen Konfiguration, um die Verknüpfung anzufordern.

Hinweis: Verwenden Sie entweder die Methode Accounts.update oder Accounts.patch. Probieren Sie am besten eine Version mit jeder Methode aus, um den Unterschied zu verstehen.

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, einen HTTP-Fehler 401. In den Shopping-Beispielen finden Sie ein Beispiel für die Verwendung des exponentiellen Backoffs, um Methoden in AccountWorkflow.java noch einmal zu versuchen. Dabei wird die retryFailures Methode aus BaseWorkflowSample.java verwendet.

Zusatzaufgabe: Erstellung der Verknüpfung überprüfen, indem Sie die Informationen zum Google Ads- und Merchant Center-Konto abrufen

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

Hinweis: Auf der Seite der Content API sollten Sie sich die Methode Accounts.get ansehen. Auf der Google Ads-Seite sollten Sie die getServiceLinks Methode des CustomerServiceInterface Objekts verwenden.

Die Welt steht Ihnen offen

Wenn Ihnen weitere Änderungen einfallen, probieren Sie sie aus. Referenzcode für Ihre Ideen finden Sie in den Google Shopping-Beispielen und im examples Verzeichnis im Quellcode der Google Ads-Clientbibliothek für Java.