Berichte mit Null-Impressionen und Strukturberichte

AdWords API-Entwickler möchten in Berichten häufig nicht nur Leistungsstatistiken, sondern auch strukturelle Informationen zu Konten abrufen.

In diesem Leitfaden wird behandelt, wie Statistiken zu Null-Impressionen in Berichten interpretiert und verwaltet und zum Aufbau einer Kontostruktur verwendet werden.

Statistiken zu Null-Impressionen in Berichten

In Ihren Berichten können Statistiken für Null-Impressionen für nicht angezeigte Entitäten auftauchen. Dafür kann es verschiedene Gründe geben. So sind diese Entitäten eventuell nicht zum Anzeigen vorgesehen oder sie waren im Berichtszeitraum pausiert.

Diese Null-Impressionen sind zur Berechnung der Leistung eigentlich überflüssig. Sie sind jedoch erforderlich, um den kompletten Inhalt des Kontos herunterzuladen.

Berichte mit Null-Impressionen werden verwendet, um Entitätsstrukturen in einem Konto zu erkennen oder schnell eine lokale Datenbank zu synchronisieren, ohne eine Serie teurer get()-Aufrufe der API ausführen zu müssen. Indem Sie Null-Impressionen in Ergebnisse einschließen, können Sie die Struktur einer beliebigen Kontoentität mit einem einzigen Aufruf erkennen.

Null-Impressionen einschließen und ausschließen

Daten zu Null-Impressionen können in allen normalen Leistungsberichten zurückgegeben werden. Sie sollten daher je nach Anwendungsfall Null-Impressionen immer explizit einschließen oder ausschließen. Sie vermeiden dadurch jede Zweideutigkeit in Ihren Anfragen, sodass von der API ein aussagekräftiger Fehler gemeldet werden kann, wenn die Anfrage eine ungültige Kombination aus Berichtsfeldern und Verhalten bei Null-Impressionen enthält.

Wann sollten Null-Impressionen eingeschlossen werden?

Null-Impressionen sind nützlich, wenn Sie Entitätsstrukturen in einem Konto in einem einzigen Aufruf darstellen möchten. The alternative is making numerous API requests which may trigger rate limits.

Wenn Sie beispielsweise den Keyword-Leistungsbericht für Id und Criteria anfragen und dabei Null-Impressionen ausschließen, werden möglicherweise nur sehr wenige Ergebnisse abgerufen. Wenn Sie jedoch Null-Impressionen einschließen und Felder wie CampaignId und AdGroupId hinzufügen, können Sie die derzeit bekannten Keywords verarbeiten und mit ihnen eine Struktur aufbauen.

Wann sollten Null-Impressionen ausgeschlossen werden?

Null-Impressionen sind nützlich, um Entitätsstrukturen zu erkennen. Sie sollten jedoch normalerweise aus Leistungsberichten ausgeschlossen werden. Der Ausschluss von Null-Impressionen ist beispielsweise sinnvoll, um die Größe der Antwort zu verringern oder sich nur auf aussagekräftige Leistungsstatistiken in einem bestimmten Zeitraum zu konzentrieren. Dies ist insbesondere hilfreich, wenn ein bestimmter Bericht sehr viele pausierte Kampagnen enthält, da Null-Impressionen den Ergebnisumfang unnötig aufblähen können.

Null-Impressionen einschließen

Legen Sie den includeZeroImpressions-HTTP-Header auf true fest, um Null-Impressionen in die Berichtausgabe einzuschließen.

Wenn dieser Header auf true festgelegt ist, werden in Berichten keine Zeilen mit Messwerten ausgeschlossen. Zusätzlich sind Zeilen mit Null-Impressionen enthalten.

Null-Impressionen ausschließen

Es gibt zwei Möglichkeiten, um Null-Impressionen explizit aus Berichten auszuschließen:

  • Legen Sie den includeZeroImpressions-HTTP-Header auf false fest.
  • Verwenden Sie ein Prädikat.

includeZeroImpressions-HTTP-Header auf "false" festlegen

Die einfachste Möglichkeit zum Ausschluss von Null-Impressionen besteht darin, den includeZeroImpressions-HTTP-Header auf false festzulegen.

Wenn dieser Header auf false festgelegt ist, werden in Berichten nur Zeilen ausgegeben, in denen mindestens eines der abgerufenen Metric-Felder einen Wert ungleich Null hat.

Null-Impressionen mit einem Prädikat ausschließen

Sie können Null-Impressionen ausschließen, indem Sie für das Feld Impressions ein Prädikat mit dem Operator GREATER_THAN und dem Wert 0 hinzufügen.

Der XML-Code für dieses Prädikat sieht so aus:

<predicates>
  <field>Impressions</field>
  <operator>GREATER_THAN</operator>
  <values>0</values>
</predicates>

Hier ist die entsprechende AWQL-Anweisung:

WHERE Impressions > 0

Null-Impressionen implizit ausschließen

Zeilen mit Null-Impressionen werden implizit ausgeschlossen, wenn in einer Berichtsanfrage ein Feld enthalten ist, das keine Null-Impressionen unterstützt. Das Verhalten bei Null-Impressionen für die einzelnen Felder sehen Sie im Attribut Unterstützt Null-Impressionen auf den Seiten mit Berichtstypen.

Sie sollten sich jedoch nicht auf implizite Ausschlüsse verlassen, da sich durch das Hinzufügen oder Entfernen eines Felds aus Ihrer Anfrage das Verhalten des Berichts ändern könnte.

Strukturberichte

Wenn Sie die API-Dienste zum Sammeln umfangreicher Daten in Ihrem Konto verwenden, kann dieser Vorgang insbesondere bei zunehmender Größe Ihres Kontos lange dauern.

Mit AdWords-Berichten bietet sich eine einfachere Möglichkeit, grundlegende strukturelle Informationen zu Ihrem Konto und samt zugehörigen Entitäten abzurufen: In Berichten können Sie Daten wie Objekt-IDs, -Namen und -Werte schnell zurückgeben, um das Grundgerüst Ihres Kontos darzustellen. Anschließend können Sie Elemente identifizieren, über die Sie mehr wissen möchten, und mit ihren Objekt-IDs Details mithilfe der API abrufen.

Die Dokumentation für die Berichtstypen zeigt, welche Spalteneinträge für die einzelnen Kontoobjekte abgerufen werden können. Die Titel dieser Spalten können auch programmatisch mithilfe der getReportFields()-Methode des ReportDefinitionService abgerufen werden. Durch sorgfältige Auswahl der Berichtsspalten erhalten Sie genügend Informationen, um die Struktur Ihres Kontos nachzubauen.

Beispiel zu Kampagnen

In diesem Beispiel wird gezeigt, wie relevante Daten zu den einzelnen Kampagnen in einem Konto gesammelt werden können. Verwenden Sie zum Sammeln dieser Daten eine AWQL-Anfrage. Speichern Sie daraufhin die zurückgegebenen Daten in einer lokalen Datenbank. Sie können dann mit lokalen SELECT-Anfragen die Strukturtabelle erstellen, an der Sie interessiert sind.

Mit den folgenden Schritten und Code-Snippets wird eine Kampagnentabelle aufgebaut:

  1. Fragen Sie Kampagnendaten aus Berichten ab, indem Sie den AWQL-Anfragestring erstellen. Geben Sie dabei alle erforderlichen Spaltenüberschriften aus dem Bericht "Kampagnenleistung" an. Darüber hinaus müssen auch der Berichtstyp und ein Zeitraum für die Abfrage angegeben werden. Anschließend wird diese Abfrage verwendet, um den Bericht zu erstellen, und dabei CSV als Downloadformat festgelegt.

    SELECT CampaignStatus, CampaignId, CampaignName, ExternalCustomerId,
        CustomerDescriptiveName, Amount, BiddingStrategyId, Impressions
    FROM CAMPAIGN_PERFORMANCE_REPORT
    DURING YESTERDAY
    

  2. Erstellen Sie eine lokale Kampagnentabelle. Von der folgenden Anweisung wird die Tabelle erstellt. Dabei werden die Spaltentitel und deren Typ in der SQLite-Tabelle aufgeführt.

    CREATE TABLE campaigns (Status STRING, id LONG, name STRING, extCID LONG,
        custName STRING, amount FLOAT, biddingStrategyId LONG, impressions INTEGER)
    

  3. Füllen Sie die Kampagnentabelle aus. Die SQL-Anweisung unten fügt Einträge in die Tabelle campaigns ein. Legen Sie für jedes "?" einen Parameterwert fest. Verwenden Sie dazu die Werte im heruntergeladenen Bericht.

    INSERT INTO campaigns (Status, id, name, extCID, custName, amount,
        biddingStrategyId, impressions) VALUES (?, ?, ?, ?, ?, ?, ?, ?)
    

Berichtformate

Berichte sind in verschiedenen Formaten verfügbar (z. B. CSV oder XML). Bei Auswahl von CSV kann der Antwortstream jedoch ganz einfach sofort verfügbare Bibliotheken durchlaufen, um die einzelnen Einträge in ein Objektformat Ihrer Wahl zu filtern. Darüber hinaus ist die CSV-Ausgabe präziser und die Verarbeitung läuft häufig zügiger ab.

Standardmäßig sind CSV-Berichte wie folgt aufgebaut: in der ersten Zeile ein Berichtskopf, in der zweiten Zeile die Spaltenüberschriften, danach die Ergebnisse und schließlich eine zusammenfassende Total-Zeile. Hier sehen Sie das Beispiel einer Antwort aus dem Bericht "Kampagnenleistung". Er veranschaulicht das Standardformat:

"CAMPAIGN_PERFORMANCE_REPORT (Apr 1, 2015-Apr 6, 2015)"
Campaign state,Campaign ID,Campaign,Customer ID,Account,Cost,Bid Strategy Name,Impressions
paused,143072203,Search + DSAs,1234567890,My AdWords Account,0, --,0
paused,168682400,Interplanetary Cruise 1396462861759,1234567890,My AdWords Account,0, --,0
paused,168682099,Interplanetary Cruise 1396462699054,1234567890,My AdWords Account,0, --,0
enabled,238539688,Campaign 1234,1234567890,My AdWords Account,5970000, --,902
Total, --, --, --, --,5970000, --,902

In diesem Standardformat folgen auf die Zeile mit dem Berichtskopf die angefragten Spaltenüberschriften in der zweiten Zeile. Die zurückgegebenen Spalten sind in der gleichen Reihenfolge aufgeführt, wie in der Anfrage festgelegt. Haben Sie doppelte Spalten angefragt, wird das zweite Vorkommen ausgelassen. Die Zusammenfassungszeile (Total) schließt den Bericht ab.

Wenn Sie die Daten parsen und in eine Datenbank einfügen, müssen die ersten zwei Zeilen ignoriert werden. Fügen Sie dann alle restlichen Zeilen bis auf die Total-Zeile ein, die ebenfalls ignoriert werden muss. Alternativ können Sie optionale Header in der Anfrage festlegen, sodass der Berichtskopf, die Spaltenüberschriften und die Zusammenfassung in der Antwort fehlen und nur die reinen Daten übrig bleiben.

Sie können diese Schritte für Anzeigengruppen, Anzeigen und Kriterien wiederholen und anschließend SQL-Anweisungen zum Abfragen der soeben gefüllten lokalen Datenbank verwenden. Passen Sie dieses Beispiel an, damit die gesammelten Daten für Ihren Anwendungsfall passen. Hier sehen Sie zwei Varianten:

SELECT * FROM campaigns
LEFT OUTER JOIN adGroups ON campaigns.id=adGroups.campaignId
LEFT OUTER JOIN ads ON ads.adAdGroupId=adGroups.adGroupId

oder

SELECT * FROM criteria
JOIN keywords
WHERE criteria.critType='Keyword' AND keywords.keywordId=criteria.critId

Tipps und Tricks

Wenn Sie mit dieser Methode Kontodaten abrufen, sollten Sie folgende Hinweise berücksichtigen:

  • Bei der Anfrage bestimmter Berichte kann das Einschließen von Spalten, die die Rückgabe von Zeilen mit Null-Impressionen verhindern, dazu führen, dass Sie keine Ergebnisse erhalten. Das Feld KeywordId im Bericht "Anzeigenleistung" ist ein solcher Fall. Dies geht aus der Spalte Anmerkungen für dieses Feld hervor. Außerdem steht dort der Wert False in der Spalte Unterstützt Null-Impressionen. Andere Spalten können sich gegenseitig ausschließen, beispielsweise ConversionTypeName und Clicks. Sie sollten diese Spalten beim Herunterladen von Strukturdaten ausschließen. Verwenden Sie stattdessen Spalten, die in der Spalte Verhalten als Attribut aufgeführt sind.

  • Sie sollten Spalten nicht doppelt anfordern, da diese aus der Antwort entfernt werden und eventuell Fehler beim Parsen verursachen. In der Spalte Anmerkungen auf der Seite zu Berichtstypen finden Sie Angaben dazu, wie Spalten formatiert sind.

  • Wenn Sie nicht die optionalen Header zum Unterdrücken der Zusammenfassungszeile Total verwenden und stattdessen das Parsen beenden, sobald das Wort Total auftritt, müssen Sie beim Auswählen der ersten Spalte in Ihrer AWQL-Abfrage darauf achten, dass das Wort Total nicht als einer der Werte in dieser Spalte vorkommt. Andernfalls würde das Parsen vorzeitig beendet. So könnten Sie beispielsweise IDs problemlos als erste Spalte verwenden, weil es sich hier um Long-Werte handelt. Im Beispiel haben wir die Spalte Status ausgewählt, die Strings mit einem eingeschränkten Satz von Werten enthält.

  • Stellen Sie sicher, dass Sie den richtigen Typ für die einzelnen Spalten verwenden, da beim Parsen dieser Werte in die korrekten Werte aus Strings Ausnahmefehler ausgelöst werden, wenn Sie unerwartete Daten erhalten und dann einen typspezifischen String-Parser dafür aufrufen.

Feedback geben zu...