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 zu den Grundlagen von AdWords-Konten und Zugriffsebenen auffrischen möchten, sehen Sie sich die Seiten zu Verwaltungskonten und Zugriffsebenen in der AdWords-Hilfe an.

Konten erstellen und verwalten

Mit den API-Diensten CustomerService und ManagedCustomerService werden Konten erstellt, Kontoinformationen abgerufen und Kontoverknüpfungen verwaltet. Verwenden Sie AccountLabelService, um Kontolabels zu verwalten.

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, etwa die Felder autoTaggingEnabled und conversionTrackingSetting.

Wenn bei einer Anfrage keine clientCustomerId angegeben wird und direkt über das authentifizierte Konto auf das Konto zugegriffen werden kann, enthält die Antwort mehrere Einträge. 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>

Die Referenzdokumentation enthält eine Liste von Werten für Währungen und Zeitzonen.

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>
    <customerId>789</customerId>
    <canManageClients>false</canManageClients>
    <currencyCode>ZAR</currencyCode>
    <dateTimeZone>Pacific/Pago_Pago</dateTimeZone>
 </entries>
 <entries>
    <name>Adwords Test Manager Account</name>
    <customerId>123</customerId>
    <canManageClients>true</canManageClients>
    <currencyCode>USD</currencyCode>
    <dateTimeZone>America/New_York</dateTimeZone>
 </entries>
 <entries>
    <name>myaccount</name>
    <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:

Das Feld canManageClients ist schreibgeschützt und wird beim Erstellen eines neuen Kundenkontos ignoriert.

Im Ordner Kontoverwaltung jeder Clientbibliothek gibt es ein Codebeispiel für das Erstellen von Konten:

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.

Beim folgenden Aufruf werden alle ausstehenden Einladungen für das Verwaltungskonto zurückgegeben:

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 festlegen, um ausstehende Einladungen für diese Konten zurückzugeben. clientCustomerIds muss über die Hierarchie des aktiven Kontos verwaltet werden, damit die zugehörigen Verknüpfungen zu sehen sind. Wenn der aktive Nutzer ein Kundenkonto hat, werden nur ausstehende Einladungen für dieses Konto angezeigt.

Bei dieser Anfrage werden PendingInvitations (ausstehende Einladungen) mit ManagedCustomer-Datensätzen zurückgegeben. Die Felder name, 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 die NEW_MANAGER_CID als managerCustomerId der Verknüpfung und geben Sie im MoveOperation-Vorgang unter oldManagerCustomerId die bisherige MANAGER_CID 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.

Verwaltungskonto-Limit

Ihr Verwaltungskonto kann die Höchstzahl von verknüpfbaren Konten erreichen. In diesem Fall müssen Sie ein paralleles Verwaltungskonto der obersten Ebene erstellen, damit Sie weitere Kundenkonten verwalten können.

Damit Sie auf das neue Verwaltungskonto der obersten Ebene zugreifen können, müssen Sie die OAuth2-Autorisierung dafür erneut durchführen. Für API-Anfragen verwenden Sie weiterhin das Entwickler-Token Ihres primären Verwaltungskontos.

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.

Während Sie auf die Tokengenehmigung warten, sind bereits Aufrufe an Testkonten möglich. 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.

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

In dieser Struktur können über "Verwaltungskonto 3" nur Aufrufe für "Kundenkonto C" vorgenommen 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 über "Hauptverwaltungskonto 1" daher nur Aufrufe für "Kundenkonto D" möglich.

Wenn Sie eines der Verwaltungskonten verwenden, legen Sie die 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 folgende 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.

  • Mit TargetingIdeaService und TrafficEstimatorService werden Beispieldaten für Testkonten zurückgegeben.
  • 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 Übersichten auf über das Konto ausgelieferten Anzeigen basieren.
  • Die Hierarchie eines Testverwaltungskontos darf maximal 50 Konten umfassen.
  • In Testkonten können keine mutate-Vorgänge an BudgetOrderService gesendet werden, da in den Konten keine Abrechnungseinstellungen festgelegt sind.

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 zu senden. Sie können eine Datei wie die oben gezeigte 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...