Einführung

Dieses Dokument richtet sich an Entwickler, die mit der AdSense Host API Informationen zu ihrem AdSense-Konto abrufen möchten. In diesem Dokument wird vorausgesetzt, dass Sie sich mit Webprogrammierung und Webdatenformaten auskennen.

Inhalt

Bevor Sie beginnen

AdSense-Konto einrichten

Sie benötigen ein AdSense-Konto, um Tests durchführen zu können. Falls Sie bereits über ein Testkonto verfügen, können Sie ohne weitere Vorbereitung auf die Benutzeroberfläche von AdSense zugreifen, um die Testdaten einzurichten, zu bearbeiten und aufzurufen.

AdSense kennenlernen

Falls Sie mit den AdSense-Begriffen noch nicht vertraut sind, lesen Sie die einführenden Informationen zu AdSense und experimentieren Sie mit der Benutzeroberfläche, bevor Sie mit der Codierung beginnen.

Anwendung registrieren

Sie können die AdSense Host API nur verwenden, wenn Sie die von Ihnen entwickelte Anwendung bei Google registrieren:

  1. Navigieren Sie zur APIs-Konsole.
  2. Melden Sie sich entweder in Ihrem Google-Konto an oder erstellen Sie ein Konto.
  3. Erstellen Sie ein neues Projekt.
  4. Klicken Sie im neu erstellten Projekt in der AdSense Host API auf den Link "Request access" (Zugriff anfordern).

Führen Sie für OAuth 2.0-Anwendungen die zusätzlichen Schritte aus, die unter "OAuth 2.0 für den Zugriff auf Google APIs verwenden" beschrieben sind.

Hinweis: Verwenden Sie zur Registrierung Ihr Entwicklerkonto, also das Konto, das für die Nutzer Ihrer Anwendung als Entwickler erscheinen soll. Das Konto muss nicht mit einem AdSense-Log-in verknüpft sein, da die Nutzer den Zugriff auf ihre eigenen Konten gewähren, wenn sie die Anwendung verwenden.

Grundlegende Informationen zur AdSense Host API

Grundbegriffe

Die AdSense Host API beruht auf einigen AdSense-Grundbegriffen:

  • Ad-Clients: Ad-Clients stellen eine Verknüpfung zwischen einem AdSense-Konto und einem AdSense-Produkt dar, beispielsweise contentbezogenen Anzeigen oder Suchanzeigen. Ein AdSense-Konto kann über einen oder mehrere Ad-Clients verfügen.
  • Channels: Channels sind Tools, mit denen Sie die Leistung einer bestimmten Seite oder Domain erfassen können.
  • Berichte: Mit Berichten erhalten Sie Informationen zu Ihren Einnahmen und zu den Auswirkungen auf diese Einnahmen. Sie können Berichte für ein gesamtes Konto oder einen Teil Ihres Inventars erstellen, indem Sie Channels verwenden.

Unterstützte Vorgänge

In der Tabelle unten sind die Vorgänge beschrieben, die von der API derzeit unterstützt werden.

Vorgang Beschreibung REST-HTTP-Zuordnungen
list Listet alle Ressourcen einer Sammlung auf. Für einen Sammlungs-URI ist dies GET.
get Ruft eine bestimmte Ressource ab. Für einen Ressourcen-URI ist dies GET.
generate Generiert ein Ergebnis anhand einer angegebenen Ressource. Wird nur für Berichte verwendet Für einen Sammlungs-URI ist dies GET/POST, wobei Sie die Ressource als Definition für die Generierung übergeben.

Alle Vorgänge erfordern eine Authentifizierung.

Aufrufstil

REST steht für einen Softwarearchitekturstil, der einen komfortablen und einheitlichen Ansatz für die Anfrage und Änderung von Daten bietet.

Das Akronym REST steht für Representational State Transfer. Im Zusammenhang mit Google-APIs bezieht sich dies auf HTTP-Verben für den Abruf und die Änderung von Daten, die von Google gespeichert wurden.

In einem RESTful-System werden Ressourcen in einem Datenspeicher gespeichert. Ein Client sendet eine Anfrage, dass der Server eine bestimmte Aktion ausführen soll, z. B. eine Ressource erstellen, abrufen, aktualisieren oder löschen. Der Server führt die Aktion aus und sendet eine Antwort, häufig in Form einer Darstellung der angegebenen Ressource.

In den RESTful-APIs von Google gibt der Client eine Aktion mithilfe eines HTTP-Verbs an, beispielsweise POST, GET, PUT oder DELETE. Die Ressource wird mit einem global eindeutigen URI in folgendem Format festgelegt:

https://www.googleapis.com/apiName/apiVersion/resourcePath?parameters

Da alle API-Ressourcen über eindeutige URIs verfügen, auf die per HTTP zugegriffen werden kann, können mit REST Daten zwischengespeichert werden. Zudem wurde diese Architektur so optimiert, dass sie sich für die im Web verteilte Infrastruktur eignet.

Weitere für Sie möglicherweise interessante Informationen zu REST finden Sie in den folgenden Dokumenten von Drittanbietern:


REST in der AdSense Host API

Die unterstützten Vorgänge beziehen sich direkt auf die REST-HTTP-Verben wie unter "AdSense Host API-Vorgänge" beschrieben.

Für AdSense Host API-URIs muss ein spezifisches Format verwendet werden:

https://www.googleapis.com/adsensehost/v4.1/resourceID?parameters

Dabei ist resourceID die Kennung für einen Ad-Client, URL-Channel, benutzerdefinierten Channel oder die Berichtsammlung. parameters steht für alle Parameter, die auf die Abfrage angewendet werden können.

Anhand des Formats der Pfaderweiterungen von resourceID können Sie die Ressource identifizieren, auf der Sie momentan arbeiten. Beispiel:

https://www.googleapis.com/adsensehost/v4.1/adclients
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId
https://www.googleapis.com/adsensehost/v4.1/adclients/adClientId/urlchannels
...

Die vollständige Gruppe von URIs, die für die einzelnen unterstützten Vorgänge in der API verwendet wird, ist im Dokument AdSense Host API-Referenz zusammengefasst.

Im Folgenden sehen Sie ein Beispiel für die Funktionsweise in der AdSense Host API.

Liste der Ad-Clients:

GET https://www.googleapis.com/adsensehost/v4.1/adclients/

Datenformat

JSON (JavaScript Object Notation) ist ein gängiges sprachunabhängiges Datenformat, das eine einfache Textdarstellung beliebiger Datenstrukturen bietet. Weitere Informationen erhalten Sie unter www.json.org.

Anfragen senden

Anfragen autorisieren

Jede Anfrage, die mit Ihrer Anwendung an die AdSense Host API gesendet wird, muss ein Autorisierungstoken enthalten. Anhand dieses Tokens wird Ihre Anwendung Google gegenüber identifiziert.

Informationen zu Autorisierungsprotokollen

In Ihrer Anwendung muss OAuth 2.0 verwendet werden, damit Anfragen autorisiert werden können. Andere Autorisierungsprotokolle werden nicht unterstützt.

Anfragen mit OAuth 2.0 autorisieren

Alle Anfragen an die AdSense Host API müssen von einem authentifizierten Nutzer autorisiert werden.

Die einzelnen Schritte des Autorisierungsprozesses für OAuth 2.0 können je nach Art der von Ihnen geschriebenen Anwendung variieren. Der folgende allgemeine Ablauf gilt für alle Anwendungsarten:

  1. Wenn Sie Ihre Anwendung erstellt haben, registrieren Sie sie mit Google Developers Console. Von Google werden dann Informationen bereitgestellt, die Sie später benötigen, beispielsweise eine Client-ID und ein Client-Schlüssel.
  2. Aktivieren Sie die AdSense Management API in der Google Developers Console. Überspringen Sie diesen Schritt, wenn die API nicht in der Google Developers Console aufgeführt wird.
  3. Wenn die Anwendung Zugriff auf Nutzerdaten benötigt, fordert sie von Google einen bestimmten Scope (Zugriffsumfang) an.
  4. Daraufhin wird ein Bestätigungsbildschirm angezeigt, in dem der Nutzer aufgefordert wird, seine Anwendung zur Anfrage einiger Daten zu autorisieren.
  5. Stimmt der Nutzer zu, erteilt Google Ihrer Anwendung ein Zugriffstoken, das für kurze Zeit gültig ist.
  6. Ihre Anwendung fordert Nutzerdaten an und das Zugriffstoken wird der Anfrage beigefügt.
  7. Wenn Google ermittelt, dass Ihre Anfrage und das Token gültig sind, werden die angeforderten Daten zurückgegeben.

Einige Anfragen enthalten zusätzliche Schritte, beispielsweise die Verwendung von Aktualisierungstoken zum Erhalt neuer Zugriffstoken. Ausführliche Informationen zu den Workflows für verschiedene Anwendungsarten finden Sie in der OAuth 2.0-Dokumentation von Google.

Im Folgenden sind die Informationen zum OAuth 2.0-Scope für die AdSense Host API angegeben:

Scope Bedeutung
https://www.googleapis.com/auth/adsensehost Lese-/Schreibzugriff auf AdSense-Daten

Damit der Zugriff mit OAuth 2.0 angefordert werden kann, muss Ihre Anwendung über die Informationen zum Scope sowie die Informationen verfügen, die von Google während der Registrierung der Anwendung bereitgestellt werden, z. B. Client-ID und/oder Client-Schlüssel.

Tipp: Die Google APIs-Client-Bibliotheken können einen Teil des Autorisierungsprozesses für Sie übernehmen. Sie sind für verschiedene Programmiersprachen verfügbar. Weitere Informationen erhalten Sie auf der Seite "Bibliotheken und Beispiele".

Weitere Informationen erhalten Sie im Abschnitt OAuth 2.0.

Eine Anfrage senden

Der letzte Schritt besteht darin, die API-Anfrage zu senden. Falls Sie keine Clientbibliotheken verwenden, können Sie in der Referenzdokumentation nachsehen.

Wenn Sie die Clientbibliotheken verwenden, ist diese Aufgabe erheblich einfacher. Unter "Beispiele und Bibliotheken" erhalten Sie eine vollständige Anleitung, wie Sie mit der Java-, Python-, PHP- oder JavaScript-Clientbibliothek Ihre erste Anfrage senden.

OAuth 2.0

In der AdSense Host API wird OAuth 2.0 zur Authentifizierung und Autorisierung eingesetzt. Aufgrund einiger Besonderheiten des AdSense Host-Verwendungsmodells werden einige Aspekte möglicherweise etwas anders gehandhabt, als Sie es von anderen Google APIs gewohnt sind.

Teilnehmer

An OAuth 2.0-Anfragen sind drei Entitäten beteiligt:

  • der Nutzer, der den Zugriff auf persönliche Daten erteilt
  • der Entwickler, der über die Anwendung den Zugriff auf die Nutzerdaten anfordert
  • das System von Google, mit dem die Teilnehmer authentifiziert werden und der API-Dienst bereitgestellt wird

Bei der AdSense Host API sind der Nutzer und der Entwickler aber tatsächlich ein und dieselbe Person, da Sie als Entwickler die API verwenden, um auf Ihr eigenes AdSense-Konto und über dieses wiederum auf die Publisher-Konten zuzugreifen.

Projekt erstellen

Sie können über die entsprechende Seite in Ihrer APIs-Konsole neue Projekte erstellen.
Abbildung 1: Neues Projekt in der APIs-Konsole

Wie bei anderen Google-APIs muss zunächst ein neues Projekt in der APIs-Konsole erstellt werden. Das Google-Konto, das Sie zur Erstellung des Entwicklerprojekts verwenden, muss für den Zugriff auf die AdSense Host API auf die weiße Liste gesetzt worden sein. Verwenden Sie also entweder das Sandbox-Konto, das wir bei der Anmeldung für Sie erstellt haben, oder Ihr AdSense-Produktionskonto, wenn Sie die API bereits implementiert haben und einsetzen.

Auf dem Tab "Services" können Sie die aktiven APIs in Ihrem Projekt auswählen.
Abbildung 2: Aktivierte und deaktivierte APIs für ein Projekt

Weitere Informationen zur Erstellung von Google APIs-Projekten finden Sie in der Dokumentation zur APIs-Konsole.

API-Zugriff einrichten

Sobald Sie ein Projekt erstellt haben, muss der API-Zugriff für das Projekt aktiviert werden, indem eine OAuth2.0-Client-ID erstellt wird.

Sie können OAuth 2.0-Clients auf dem Tab "API Access" erstellen.
Abbildung 3: Neuen OAuth 2.0-Client in der APIs-Konsole erstellen

Es stehen mehrere Möglichkeiten zur Auswahl, aber wir empfehlen die Erstellung eines Projekts vom Typ Installierte Anwendung, da dies die nächsten Schritte vereinfacht.

Einmal authentifizieren, für immer speichern

Authentifizieren Sie sich jetzt mit Ihrem AdSense-Konto. Verwenden Sie hierzu ein kleines Skript oder eine Testanwendung. Sehen Sie sich unseren Beispielcode an.

Speichern Sie nach der Authentifizierung das Aktualisierungs-Token, das im Autorisierungsschritt zurückgegeben wurde. Dies ist ein langlebiges Token, das erst abläuft, wenn der Zugriff ausdrücklich widerrufen wird. Da Sie selbst der Nutzer sind, werden Sie den Zugriff auf Ihre eigene Anwendung vermutlich nicht verweigern.

Speichern Sie das Aktualisierungs-Token für alle zukünftigen Authentifizierungsanfragen im Datenspeicher Ihrer Anwendung.

Gespeichertes Token in Ihrer Anwendung verwenden

Sobald Sie ein Aktualisierungs-Token haben, ist es nicht mehr wichtig, ob es mit dem Ablauf für eine Webserveranwendung oder eine Installierte Anwendung generiert wurde. Sie können es einfach verwenden, um bei Bedarf Tokenaktualisierungen für neue Zugriffstoken anzufordern. Wenn Sie eine unserer Clientbibliotheken verwenden, können Sie in der Dokumentation nachlesen, wie eigene Token angegeben werden können. Möglicherweise muss eine automatisch generierte Datei oder ein Datenbankeintrag bearbeitet werden.

Zusammenfassung

Im Endeffekt wird der OAuth 2.0-Workflow nur einmal ausgeführt. Anschließend finden alle Anfragen im Hintergrund statt, ohne dass ein manueller Eingriff des Endnutzers Ihrer Website, also des Publishers, oder von Ihnen als Entwickler notwendig ist.

Ankündigungen

In den AdSense-API-Ankündigungen erhalten Sie stets aktuelle Informationen zu neuen Versionen und Funktionen sowie zu wichtigen Dienstupdates.

Feedback geben zu...

AdSense Host API
AdSense Host API