Konten verwalten

In diesem Leitfaden wird erläutert, wie Sie AdWords-Konten (einschließlich Verwaltungs-, Kunden- und Testkonten) mithilfe der AdWords API verwalten.

Es wird vorausgesetzt, dass Sie mit Verwaltungs- und Kundenkonten in AdWords vertraut sind. Wenn Sie Ihre Kenntnisse der Grundlagen von AdWords-Konten und Zugriffsebenen auffrischen möchten, finden Sie entsprechende Informationen in der AdWords-Hilfe auf den Seiten zu Verwaltungskonten und Zugriffsebenen.

Konten erstellen und verwalten

CustomerService und ManagedCustomerService sind die API-Dienste, die zum Erstellen von Konten, Abrufen von Kontoinformationen und Verwalten von Kontoverknüpfungen verwendet werden. Verwenden Sie AccountLabelService zum Verwalten von Kontolabels.

CustomerService

CustomerService stellt Informationen zu Ihren Konten zur Verfügung. Von diesem Dienst wird mit der Methode getCustomers(), die keine Argumente übernimmt, eine Liste von Customer-Objekten mit Feldern wie customerId, currencyCode und dateTimeZone zurückgegeben. CustomerService hat auch eine mutate()-Methode, mit der verschiedene Attribute eines Kunden aktualisiert werden können, darunter die Felder autoTaggingEnabled und conversionTrackingSetting.

Wenn in Version 201605 oder früher keine clientCustomerId angegeben ist, enthält die Antwort einen einzelnen Eintrag für das authentifizierte Konto. Wenn Sie ein Verwaltungskonto authentifizieren, müssen Sie eine clientCustomerId angeben, um Informationen zu einem bestimmten Konto abzurufen (siehe Authentifizierung weiter unten).

Wenn ab Version keine 201607 keine clientCustomerId angegeben ist, enthält die Antwort mehrere Einträge, falls auf ein Konto direkt über das authentifizierte Konto zugegriffen werden kann. Wenn Sie nur Ergebnisse für ein einzelnes Konto abrufen möchten, müssen Sie die clientCustomerId in Ihrer Anfrage angeben.

Beispielantwort:

<rval>
   <customerId>123456789</customerId>
   <currencyCode>USD</currencyCode>
   <dateTimeZone>America/New_York</dateTimeZone>
   <descriptiveName>myaccount</descriptiveName>
   <canManageClients>false</canManageClients>
</rval>

The Reference documentation contains a list of values for currencies and timezones.

ManagedCustomerService

ManagedCustomerService hat ebenfalls eine get()-Methode und einen allgemeinen Selektor. Es gibt mehr Auswahlfelder als bei CustomerService. Weitere Informationen finden Sie in der Dokumentation.

Neben einer Liste der Konten, die die Kriterien des Selektors erfüllen, erhalten Sie eine Liste der ManagedCustomerLink-Objekte, die die Beziehung zwischen Konten beschreiben.

<rval>
 <totalNumEntries>3</totalNumEntries>
 <Page.Type>ManagedCustomerPage</Page.Type>
 <entries>
    <name>Account Created with MCS</name>
    <login/>
    <companyName/>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <login>my-manager-account@example.com</login>
    <companyName/>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <login>myaccount@example.com</login>
    <companyName/>
    <customerId>456</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>456</clientCustomerId>
 </links>
 <links>
    <managerCustomerId>123</managerCustomerId>
    <clientCustomerId>789</clientCustomerId>
 </links>
</rval>

ManagedCustomerService kann auch zum Erstellen neuer Konten verwendet werden, die dann zum aktiven Nutzer gehören, bei dessen Konto es sich ebenfalls um ein Verwaltungskonto handeln muss. Ein Beispiel für eine Anfrage:

<operations>
  <operator>ADD</operator>
  <operand>
    <name>Foo</name>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </operand>
</operations>

Beispielantwort:

<rval>
  <value>
    <name>Foo</name>
    <customerId>9876543210</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
  </value>
</rval>

Felder wie companyName, login und canManageClients sind schreibgeschützt. Sie werden beim Erstellen eines neuen Kundenkontos ignoriert. ManagedCustomerService kann nicht zur Aktualisierung eines Kundenkontos verwendet werden.

Konten verknüpfen

Wenn ein Verwaltungs- mit einem oder mehreren Kundenkonten verknüpft ist, können über das Verwaltungskonto Anfragen für diese Kundenkonten durchgeführt werden.

Mit ManagedCustomerService werden Verknüpfungen zwischen Konten verwaltet. Dies ermöglicht die automatisierte Verwaltung der Kontenhierarchie:

So verknüpfen Sie ein Verwaltungskonto mit einem Kundenkonto:

  1. Sie müssen über das Verwaltungskonto eine Einladung an das Kundenkonto senden.
  2. Der Kunde muss die Einladung annehmen.

Einladungen senden

Über ein Verwaltungskonto können Sie Nutzer eines Kundenkontos oder eines anderen Verwaltungskonto einladen, deren Konten zu verwalten.

In diesem Szenario kann die MANAGER_ID das Verwaltungskonto, mit dem Sie sich authentifizieren, oder ein anderes untergeordnetes Verwaltungskonto in Ihrer Hierarchie sein. CLIENT_CID muss ein Kunden- oder Verwaltungskonto sein, das derzeit nicht über ein Verwaltungskonto in Ihrer Hierarchie verwaltet wird.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.PENDING);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.ADD);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Sie können Einladungen als ADD-Vorgang mit dem Verknüpfungsstatus PENDING senden.

Ausstehende Einladungen abrufen

Mit ManagedCustomerService.getPendingInvitations können ausstehende Einladungen, auf die noch nicht reagiert wurde, über das Kunden- oder Verwaltungskonto abgerufen werden. Sobald der Kunde die Einladung annimmt bzw. ablehnt oder die Einladung über das Verwaltungskonto widerrufen wird, ist diese nicht mehr ausstehend.

In einem ManagedCustomerService.get()-Aufruf werden nur ACTIVE Verknüpfungen angezeigt, nicht jedoch CANCELLED, REFUSED und INACTIVE Verknüpfungen.

Der folgende Aufruf gibt alle ausstehenden Einladungen für das Verwaltungskonto zurück:

PendingInvitationSelector selector = new PendingInvitationSelector();
PendingInvitation[] invitations = managedCustomerService.getPendingInvitations(selector);

Sie können in den Feldern managerCustomerIds und clientCustomerIds auch die ID des Verwaltungskontos bzw. des Kundenkontos angeben, um ausstehende Einladungen für diese Konten zurückzugeben. clientCustomerIds muss über die Hierarchie des aktiven Kontos verwaltet werden, um die zugehörigen Verknüpfungen anzuzeigen. Wenn der aktive Nutzer ein Kundenkonto hat, werden nur ausstehende Einladungen für dieses Konto angezeigt.

Diese Anfrage gibt PendingInvitations (ausstehende Einladungen) mit ManagedCustomer-Datensätzen zurück. Die Felder Name, login, companyName, customerId und canManageClients werden sowohl für den Administrator als auch für den Kunden ausgefüllt.

Einladungen widerrufen

Wenn Sie eine Einladung zum Verwalten eines Kundenkontos senden, es sich dann jedoch anders überlegen, können Sie die Einladung widerrufen, indem Sie den Verknüpfungsstatus in einem SET-Vorgang auf CANCELLED setzen. Dabei muss das aktive Konto das Verwaltungskonto sein, über das diese Verknüpfung verwaltet wird.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.CANCELLED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Kunde lehnt ab

Der Kunde kann die Einladung ebenfalls ablehnen, indem er in einem SET-Vorgang den Verknüpfungsstatus auf REFUSED setzt. Der aktive Nutzer muss in dieser Anfrage entweder mit der CLIENT_CID übereinstimmen oder diese als Kontoinhaber mit Administratorzugriff verwalten.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.REFUSED);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Kunde akzeptiert

Der Kunde nimmt die Einladung an, indem er mit SET den Verknüpfungsstatus auf ACTIVE setzt. Ebenso wie bei der Ablehnung muss der aktive Nutzer in dieser Anfrage entweder mit der CLIENT_CID übereinstimmen oder diese als Kontoinhaber mit Administratorzugriff verwalten.

LinkOperation linkOp = new LinkOperation();
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Wenn ein Kunde oder der Administrator die Verknüpfung aufheben möchte, kann LinkStatus mit SET auf INACTIVE gesetzt werden.

ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.INACTIVE);
link.setManagerCustomerId(MANAGER_CID);
linkOp.setOperand(link);
linkOp.setOperator(Operator.SET);
managedCustomerService.mutateLink(new LinkOperation[]{linkOp});

Dies kann über das Verwaltungs- oder das Kundenkonto erfolgen.

Kundenkonten verschieben

Mit ManagedCustomerService.mutateManager können Sie AdWords-Konten einfach von einem Verwaltungskonto in ein anderes verschieben. Sowohl Kunden- als auch Verwaltungskonten können mit der mutateManager()-Methode verschoben werden.

MoveOperation op = new MoveOperation();
op.setOldManagerCustomerId(MANAGER_CID);
op.setOperator(Operator.SET);
ManagedCustomerLink link = new ManagedCustomerLink();
link.setClientCustomerId(CLIENT_CID);
link.setLinkStatus(LinkStatus.ACTIVE);
link.setManagerCustomerId(NEW_MANAGER_CID);
op.setOperand(link);
managedCustomerService.mutateManager(new MoveOperation[]{op});

Sowohl der bisherige als auch der neue Administrator müssen im aktiven Konto verwaltet werden. Der Verknüpfungsstatus muss ACTIVE sein. Verwenden Sie NEW_MANAGER_CID als managerCustomerId der Verknüpfung und geben Sie im MANAGER_CID-Vorgang unter MoveOperation die bisherige oldManagerCustomerId an.

AccountLabelService

Kontolabels lassen sich zum Organisieren und Verwalten von Konten verwenden. Mithilfe von AccountLabelService können Sie Labels auf Kontoebene hinzufügen, aktualisieren oder entfernen. Mit der API können Sie auch Kontolabels eines untergeordneten Administrators verwalten.

Beschränkungen des Verwaltungskontos

Es gibt einige Beschränkungen, die Sie kennen sollten, wenn Sie mit Verwaltungskonten arbeiten. Sehen Sie sich hierzu die Referenzseite zu Systembeschränkungen an. Dort finden Sie auch eine vollständige Liste anderer Systembeschränkungen.

In AdWords-Konten werden diese Beschränkungen nur selten erreicht. Falls in einem AdWords-Konto, das Sie verwalten, eine der Beschränkungen erreicht ist, muss das Problem vor der Verknüpfung dieses Kontos behoben werden.

Achten Sie auch darauf, die Ratenbegrenzungen nicht zu überschreiten.

Authentifizierung

Für Aufrufe an die AdWords API sind ein genehmigtes Entwickler-Token und in OAuth2 generierte Anmeldedaten erforderlich, die Zugriff auf das Zielkonto gewähren.

Der einfachste Ansatz besteht in der Authentifizierung als Verwaltungskonto. Sobald das Konto authentifiziert ist, wird der Zugriff auf alle Konten unter diesem Verwaltungskonto gewährt. Die Authentifizierung erfolgt über OAuth2.

Entwickler-Token

Wenn Sie sich für die AdWords API registrieren, wird automatisch ein Entwickler-Token für Sie generiert. Direkt nach der Antragstellung steht die Genehmigung des Tokens noch aus.

While waiting for token approval, you'll be able to make calls against test accounts. Wenn das Token genehmigt ist, können Sie AdWords-Produktionskonten verwenden.

OAuth2-Anmeldedaten

Alle Anfragen an die AdWords API müssen autorisiert werden, damit Sie Änderungen vornehmen oder Daten zu einem AdWords-Konto abrufen können. Anhand der für einen API-Aufruf verwendeten OAuth2-Anmeldedaten wird festgelegt, welche Zielkonten ausgewählt werden können.

Aufrufe, die mit den Anmeldedaten eines Verwaltungskontos ausgeführt werden, können für das Verwaltungskonto oder für Konten erfolgen, für die Ihnen die OAuth2-Anmeldedaten vorliegen. Hier sehen Sie eine typische AdWords-Kontohierarchie:

Ihr Entwickler-Token kann zu "Hauptverwaltungskonto 1" oder zu einem anderen Verwaltungskonto in einer anderen Hierarchie gehören. Dies wirkt sich nicht darauf aus, welche Zielkonten Sie auswählen können. Sie müssen lediglich die Client-Kundennummer des Zielkontos angeben.

Um API-Aufrufe für "Kundenkonto A" durchzuführen, können Sie die OAuth2-Anmeldedaten eines Log-ins verwenden, der zu "Kundenkonto A" gehört, und dann den Anfrage-Header von clientCustomerId auf die Kundennummer von "Kundenkonto A", "Verwaltungskonto 2" oder "Hauptverwaltungskonto 1" setzen.

In dieser Struktur können über "Verwaltungskonto 3" nur Aufrufe für "Kundenkonto C" durchgeführt werden. Aufrufe für "Kundenkonto A" oder "Kundenkonto B" sind nicht möglich, da diese Konten nicht über "Verwaltungskonto 3" verwaltet werden. Über "Hauptverwaltungskonto 1" können Aufrufe für jedes Konto in der Hierarchie durchgeführt werden.

Aufrufe, die mit den Anmeldedaten eines Verwaltungskontos ausgeführt werden, können nur für das Verwaltungskonto oder für Konten erfolgen, die dem Verwaltungskonto in der Kontohierarchie untergeordnet sind. In dieser Hierarchie sind Aufrufe für "Kundenkonto D" nur über "Hauptverwaltungskonto 1" möglich.

Wenn Sie eines der Verwaltungskonten verwenden, legen Sie clientCustomerId auf dieses Verwaltungskonto oder eines seiner Unterkonten fest.

Testkonten

Verwaltungs- und Kundenkonten sind zur Strukturierung nützlich. Wie sieht es aber während der Entwicklung mit dem Testen von Änderungen oder dem Testen von API-Aufrufen aus, wenn Sie Ihre Produktionsumgebung nicht beeinträchtigen möchten? Dazu dienen Testkonten.

Mit Testkonten können Sie neue API-Implementierungen oder Kontokonfigurationen ausprobieren, bevor Sie diese Änderungen in Ihre Produktionsumgebung übernehmen.

Testkonten können wie Produktionskonten in einer Hierarchie eingerichtet und strukturiert werden. Während der aktiven Entwicklung bieten sie jedoch zusätzliche Vorteile. Besonderheiten von Testkonten:

  • Sie benötigen kein genehmigtes Entwickler-Token. Sie können also sofort mit der API experimentieren, auch wenn Ihre Anwendung noch nicht geprüft oder genehmigt ist.
  • Anzeigen werden nicht ausgeliefert, eine Interaktion mit Ihren Produktionskonten ist nicht möglich.
  • Sie lassen sich genau wie normale Konten in der AdWords-Weboberfläche aufrufen und bearbeiten.

Da Test- und Produktionskonten in keiner Weise interagieren können, lässt sich ein Testkonto nicht in Ihrem vorhandenen Produktionsverwaltungskonto einrichten. Sie benötigen eine neue Kontohierarchie, in der ein Testverwaltungskonto die oberste Ebene bildet.

Testkonten sind über die AdWords-Weboberfläche zugänglich und haben ein rotes Label (siehe unten).

Für Testkonten gelten dieselben Beschränkungen (einschließlich Ratenbegrenzungen) wie für Produktionskonten.

Testkonten verwenden

Um API-Anfragen bei einem Testkonto durchführen zu können, benötigen Sie ein Produktionsverwaltungskonto (kein Testverwaltungskonto) und ein Entwickler-Token, auch wenn die Genehmigung des Tokens noch aussteht.

Erstellen Sie über Ihr Produktionsverwaltungskonto ein Testverwaltungskonto, bevor Sie Testkundenkonten erstellen. Alle unter dem Testverwaltungskonto erstellten Kundenkonten werden automatisch als Testkonten gekennzeichnet.

So erstellen und verwenden Sie ein Testkonto:

  1. Falls Sie noch kein Produktionsverwaltungskonto und/oder Entwickler-Token für Produktionsverwaltungskonten haben:
    1. Erstellen Sie ein Produktionsverwaltungskonto (z. B. production-manager@mycompany.example.com).
    2. Fordern Sie im Produktionsverwaltungskonto ein Entwickler-Token an.
  2. Erstellen Sie ein Testverwaltungskonto (z. B. test-manager@mycompany.example.com). Um ein Testkonto erstellen zu können, müssen Sie ein Google-Konto haben, das noch nicht mit einem AdWords-Konto verknüpft ist. Ein neues Google-Konto können Sie unter accounts.google.com erstellen.
  3. Verwenden Sie das Entwickler-Token des Produktionsverwaltungskontos für Anfragen beim Testverwaltungskonto.
  4. Stellen Sie bei der Anforderung eines OAuth2-Aktualisierungstokens sicher, dass Sie als Nutzer des Testverwaltungskontos angemeldet sind (z. B. test-manager@mycompany.example.com).

Die nachstehende Tabelle enthält die zulässigen Interaktionen zwischen verschiedenen AdWords-Kontotypen und einem Entwickler-Token je nach Genehmigungsstatus:

Status des Produktionsentwickler-Tokens AdWords-Kontotyp Zulässig
Genehmigung ausstehend Testkonto Ja
Genehmigung ausstehend Kein Testkonto Nein
Genehmigt Testkonto Ja
Genehmigt Kein Testkonto Ja

OAuth2 für Testkonten verwenden

Um mit OAuth2 auf ein Testkonto zugreifen zu können, muss der Nutzer des Testverwaltungskontos Ihrer Client-Anwendung die Berechtigung erteilen. Stellen Sie daher bei der Anforderung eines OAuth2-Aktualisierungstokens sicher, dass Sie als Nutzer des Testverwaltungskontos und nicht des Produktionsverwaltungskontos angemeldet sind.

Wenn Sie vom Testverwaltungskonto zum Produktionsverwaltungskonto wechseln möchten, müssen Sie lediglich die Clientbibliothek so konfigurieren, dass das Aktualisierungstoken des Produktionsverwaltungskontos verwendet wird.

Anfrage-Header

Alle Anfragen bei Testkonten müssen an denselben Endpunkt wie bei Produktionskonten gesendet werden:

https://www.googleapis.com/auth/adwords/

Die SOAP-Anfrage- und -Antwort-Header entsprechen denen der Produktionskonten. Verwenden Sie für Autorisierungs-Header unbedingt die Anmeldedaten für Ihr Testkonto.

Weitere Merkmale von Testkonten

Bei Testkonten sollten Sie folgende Punkte berücksichtigen.

  • TargetingIdeaService und TrafficEstimatorService geben Beispieldaten für Testkonten zurück.
  • Da über Testkonten keine Anzeigen ausgeliefert werden, gibt es dafür auch keine Messwerte. Dies wirkt sich auf Berichte aus: Der Wert für Impressionen, Kosten usw. ist null.
  • Testkonten sind keine Klicks zugeordnet. Sie können daher nicht zum Testen von Offline-Conversion-Uploads verwendet werden.
  • DataService gibt für Testkonten keine Gebotsübersichten zurück, da Gebotsübersichten auf über das Konto ausgelieferte Anzeigen basieren.
  • Die Hierarchie eines Testverwaltungskontos darf maximal 100 Konten umfassen. Die Beschränkung für Produktionskonten ist viel höher.

Mit Testkonten entwickeln

Wenn Sie sich für den Zugriff auf die AdWords API registrieren, werden Sie möglicherweise gebeten, einige Funktionen Ihrer Anwendung zu demonstrieren. Eine dieser Funktionen sind Berichte. Diese sind jedoch nicht einfach zu emulieren, wenn Sie nur Testkonten verwenden.

Da über Testkonten keine Impressionen generiert werden, gibt es dafür auch keine Messwerte. Sie können zwar Strukturberichte herunterladen, doch gibt es darin nur Zeilen mit null Impressionen. Dies bedeutet, dass Segmente nicht funktionieren.

Wir empfehlen daher die Darstellung fiktiver Daten. Das Tokenüberprüfungsteam muss sehen, ob Ihre Anwendung mit Berichtsdaten interagieren und diese aufrufen kann. Indem Sie den Berichtsaufruf simulieren (d. h. vorgeben, dass der Berichtsaufruf erfolgreich war, und eine lokal gespeicherte Datei mit fiktiven Berichtsdaten verwenden), können Sie Berichtsdaten hinzufügen, ohne sie tatsächlich über die API abzurufen.

Stellen Sie sicher, dass die Testberichtsdaten das richtige Format haben. Wenn Sie beispielsweise einen Bericht zur Kampagnenleistung mit Datum, Kampagnenname, Kampagnen-ID, Impressionen, Klicks und Kosten generieren, erhalten Sie eine Datei wie diese:

"CAMPAIGN_PERFORMANCE_REPORT (Mar 20, 2013-Mar 23, 2013)"
Day,Campaign,Campaign ID,Impressions,Clicks,Cost
20130320,Widgets,123,1211,19,14.92
20130320,Sprockets,456,300,4,2.92
20130321,Widgets,123,901,12,9.86
20130321,Sprockets,456,340,5,3.86
20130322,Widgets,123,1065,16,11.23
20130322,Sprockets,456,509,6,5.23
20130323,Widgets,123,1005,15,10.12
20130323,Sprockets,456,287,3,1.12

Wenn Sie eine solche Datei erstellen und lokal speichern, kann der API-Aufruf über Ihre Anwendung simuliert werden. Wird der Bericht angefordert, geben Sie die gespeicherte Datei zurück und verarbeiten Sie sie, anstatt tatsächlich einen API-Aufruf durchzuführen. Sie können eine Datei wie die oben dargestellte für jeden Bericht erstellen, den Sie generieren möchten.

Mit Produktionsdaten testen

Sie können Produktionsdaten in Ihren Produktionskonten schreibgeschützt testen, wenn Sie in Ihren Anfragen den validateOnly-Header verwenden und ein genehmigtes Entwickler-Token haben.

Feedback geben zu...