Google AdWords API – Teil 2

Kampagnen und Anzeigegruppen auslesen – im zweiten Teil meiner Google AdWords Artikelreihe geht es nun um das Abfragen von Werte aus einem AdWords Konto.

Aufbau

Ein AdWords Konto ist hierarchisch folgendermaßen aufgebaut:

• AdWords Konto
  Ein AdWords Konto ist über seine AdWords ID eindeutig und stellt ein Google Account dar.
• Kampagnen
  Das um und auf bei Adwords sind die Werbekampagnen. Man kann beliebig viele anlegen. Diese können aktiv sein, es wird Werbung im Internet angezeigt, oder inaktiv bzw. pausiert. Aktive Kampagnen kosten Geld und bringen nun Kunden auf eine Seite.
• Anzeigegruppe
  Jede Kampagne besteht aus vielen Anzeigegruppen. Diese stellen eine Gruppierung der Werbemittel dar. Hierarchisch gesehen sind sie einer Kampagne zugeordnet. Einer Anzeigegruppe lassen sich Anzeigen, Keywords und Placements zuordnen.
• Anzeige (AdText)
  Ein Google Anzeigentext mit Überschrift und 2 Textzeilen. Diese sind auf der Google Suchseite zum Beispiel rechts neben den Suchergebnissen zu finden.
• Keyword
  Das sind die Suchbegriffe über die man auf die Seite kommt.
• Placement
  Das sind grafische Anzeigen. Also Grafiken oder Animationen über die der Kunde auf die Seite kommt.

Kampagnen

Das erste Ziel ist nun, dass wir uns über die Schnittstelle alle Kampagnen holen, welche zu einer AdWords ID gehören. Dazu haben wir im letzten Teil dem User Objekt die AdWords ID zugewiesen.

Kampagnen kann man mit dem CampaignService abfragen. Hierfür habe ich eine Funktion (welche auf einem Beispielcode von der Client Library basiert) geschrieben, welche alle aktiven Kampagnen als Array zurückgibt:

function GetCampaigns(AdWordsUser $user, $adwords_version) {

    // Get the service, which loads the required classes.
    $campaignService = $user->GetService('CampaignService', $adwords_version);

    // Create selector.
    $selector = new Selector();
    $selector->fields = array('Id', 'Name', 'Status');
    $selector->ordering[] = new OrderBy('Name', 'ASCENDING');

    // Filter out deleted criteria.
    $selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DELETED', 'PAUSED'));

    // Create paging controls.
    $selector->paging = new Paging(0, AdWordsConstants::RECOMMENDED_PAGE_SIZE);

    $ret = array();
    do {
        // Make the get request.
        $page = $campaignService->get($selector);

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $campaign) {
                //printf("Campaign with name '%s' and id '%s' was found with Status: '%s'\n",
                // $campaign->name, $campaign->id, $campaign->status);
                $ret[] = array(
                    'name' => $campaign->name,
                    'id' => $campaign->id,
                    'active' => (strcmp($campaign->status,'ACTIVE')==0)?1:0
                );
            }
        } else {
            //print " No campaigns were found.\n";
        }
        // Advance the paging index.
        $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
    } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

Dieser Funktion übergeben wir das in Teil 1 meiner Artikelserie erstellte User Objekt. Weiters übergeben wir auch die AdWords Version. Aktuell ist dies der String mit der Versionsnummer: ‚v201209‘.

Über das User Objekt holen wir und das CampaignService. Nun können wir die Abfrage definieren und limitieren:

• Selector
  Mit dem Selector definieren wir alle Spalten die wir von der Abfrage geliefert bekommen wollen. Eine Liste aller Spalten pro Service gibt es hier. Weiters können wir hier auch angeben nach welcher Spalte sortiert werden soll.
• Predicate
  Mit der Predicate Klasse können wir das Suchergebnis einschränken. In diesem Beispiel wollen wir nur aktive Kampagnen, schließen also alle gelöschten und pausierten Kampagnen aus.
• Paging
  Über die Paging Klasse holen wir uns das Suchergebnis. Dafür gehen wir in einer Schleife alle Zeilen durch und füllen unser Rückgabe Array mit den für die Weiterverarbeitung relevanten Daten.

Anzeigegruppen

Die Anzeigegruppen holt man sich mit dem AdGroupService. Dieses funktioniert genau wie das CampaignService. Zur Vollständigkeit hier der Code:

function GetAdGroup(AdWordsUser $user, $adwords_version) {
    // Get the service, which loads the required classes.
    $adgroupService = $user->GetService('AdGroupService', $adwords_version);

    // Create selector.
    $selector = new Selector();
    $selector->fields = array('Id', 'Name', 'CampaignId', 'Status');
    $selector->ordering[] = new OrderBy('CampaignId', 'ASCENDING');

    // Filter out deleted criteria.
    $selector->predicates[] = new Predicate('Status', 'NOT_IN', array('DELETED', 'PAUSED'));

    // Create paging controls.
    $selector->paging = new Paging(0, AdWordsConstants::RECOMMENDED_PAGE_SIZE);

    $ret = array();
    do {
        // Make the get request.
        $page = $adgroupService->get($selector);

        // Display results.
        if (isset($page->entries)) {
            foreach ($page->entries as $adgroup) {
                //printf("AdGroup with name '%s' and id '%s' was found for Campaign: '%s' and Status: '%s'\n",
                // $adgroup->name, $adgroup->id, $adgroup->campaignId, $adgroup->status);
                $ret[] = array(
                    'name' => $adgroup->name,
                    'id' => $adgroup->id,
                    'campaignId' => $adgroup->campaignId,
                    'active' => (strcmp($adgroup->status,'ENABLED')==0)?1:0
                );
            }
        } else {
            //print "No adgroups were found.\n";
        }
        // Advance the paging index.
        $selector->paging->startIndex += AdWordsConstants::RECOMMENDED_PAGE_SIZE;
    } while ($page->totalNumEntries > $selector->paging->startIndex);
    return $ret;
}

Im nächsten Teil geht es nun darum Werte der Keywords, Anzeigen und Placements auszulesen.

Teil 1 | Teil 2 | Teil 3 | Teil 4 | Teil 5 | Teil 6