AdWords Query Language (AWQL)

AWQL is a SQL‒like language for performing queries against most common AdWords API services. Jeder Dienst, der eine query()-Methode bereitstellt, wird unterstützt.

AWQL basiert auf SQL, unterstützt jedoch nicht alle Sprachelemente von SQL. So fehlen insbesondere die Klauseln JOIN und GROUP BY.

Für jeden Dienst können Sie die Liste der abfragbaren Felder über Selektorfelder ermitteln.

Außerdem können Sie mit AWQL Daten für Berichte abfragen. Eine vollständige Liste der abfragbaren Felder finden Sie unter Berichtstypen.

AWQL in Dienstaufrufen verwenden

Mit AWQL ist die Codierung eines Aufrufs in der Regel effizienter. Beispielsweise kann der folgende Selektor für CampaignService.get() verwendet werden:

<serviceSelector>
    <fields>Id</fields>
    <fields>Name</fields>
    <predicates>
        <field>Status</field>
        <operator>EQUALS</operator>
        <values>ENABLED</values>
    </predicates>
    <ordering>
        <field>Name</field>
        <sortOrder>ASCENDING</sortOrder>
    </ordering>
    <paging>
        <startIndex>0</startIndex>
        <numberResults>50</numberResults>
    </paging>
</serviceSelector>

Der analoge AWQL-Abfragestring für CampaignService.query():

SELECT Id, Name
WHERE Status = 'ENABLED'
ORDER BY Name
DESC LIMIT 0,50

In unseren Clientbibliotheken sind Codebeispiele für AWQL enthalten, unter anderem dieses komplette Codebeispiel zum Abrufen von Kampagnen mit AWQL:

Hinweise

  • Eine FROM-Klausel ist nicht erforderlich, da die Datenquelle bereits durch den Dienst festgelegt ist, an den die Anfrage gesendet wird.
  • Eine DURING-Klausel ist in Dienstaufrufen nicht zulässig, jedoch in Berichtaufrufen.
  • Im Gegensatz zu Schlüsselwörtern wie WHERE muss bei Feld- und Spaltennamen (z. B. Name) und Literalen (z. B. ENABLED) die Groß-/Kleinschreibung beachtet werden.
  • Wenn die Operatoren IN und NOT_IN in einer WHERE-Klausel verwendet werden, sind diese auf 10.000 Elemente begrenzt.

AWQL mit Berichten verwenden

AWQL wird häufig für Berichte verwendet. Geben Sie anstelle des sonst zur Angabe des XML-Fragments für Ad-hoc-Berichte verwendeten POST-Parameters "__rdxml" die beiden folgenden Parameter an:

  1. "__rdquery": enthält den AWQL-Abfragestring
  2. "__fmt": definiert das Format für den Berichtsdownload

Beispiel (POST-Text):

__rdquery=SELECT+Criteria+FROM+KEYWORDS_PERFORMANCE_REPORT+DURING+20150101,20150325&__fmt=CSV

Bei der Verwendung von AWQL für Berichte gelten besondere Regeln:

  • Die Abfrage muss in der FROM-Klausel einen Berichtstyp enthalten. Beispiel:

    SELECT Id, Criteria, AdGroupName **FROM KEYWORDS_PERFORMANCE_REPORT**

    Die in Dienstaufrufen nicht zulässige FROM-Klausel ist für Berichtsdownloads obligatorisch.

  • Zeiträume für Berichte werden in der DURING-Klausel der Abfrage definiert. Zeiträume können auf zwei verschiedene Arten angegeben werden:

    1. Als benutzerdefinierter Zeitraum mithilfe der normalen AWQL-Syntax. Beispiel:

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING 20160101,20160325

    2. Als Zeitraumtyp. Beispiel:

      SELECT Id, Criteria, AdGroupName FROM KEYWORDS_PERFORMANCE_REPORT DURING LAST_7_DAYS

  • Um Daten für alle Tage abzurufen (äquivalent zu ALL_TIME), können Sie die DURING-Klausel in der Abfrage weglassen. Dies ist jedoch nur zulässig, wenn die SELECT-Klausel der Abfrage nicht die Spalte Date oder Week enthält.

  • ORDER BY und LIMIT (Sortieren und Seitenauswahl) werden für Berichte nicht unterstützt. Wenn diese Klauseln in einer Abfrage enthalten sind, wird ein Fehler generiert.
  • Nehmen Sie die Bedingung WHERE Impressions > 0 auf, um Zeilen mit null Impressionen wegzulassen.

Formelle AWQL-Syntax

Die formelle AWQL-Syntax ist wie folgt aufgebaut:

Statement        -> SelectClause FromClause1 WhereClause?
                                 DuringClause2 OrderByClause? LimitClause?
SelectClause     -> SELECT ColumnList
FromClause       -> FROM SourceName
WhereClause      -> WHERE ConditionList
DuringClause     -> DURING DateRange
OrderByClause    -> ORDER BY Ordering (, Ordering)*
LimitClause      -> LIMIT StartIndex , PageSize

ConditionList    -> Condition (AND Condition)*
Condition        -> ColumnName Operator Value
Value            -> ValueLiteral | String | ValueLiteralList | StringList
Ordering         -> ColumnName (DESC | ASC)?
DateRange        -> DateRangeLiteral | Date,Date
ColumnList       -> ColumnName (, ColumnName)*
ColumnName       -> Literal
SourceName       -> Literal
StartIndex       -> Non-negative integer
PageSize         -> Non-negative integer

Operator         -> = | != | > | >= | < | <= | IN | NOT_IN | STARTS_WITH | STARTS_WITH_IGNORE_CASE |
                    CONTAINS | CONTAINS_IGNORE_CASE | DOES_NOT_CONTAIN | DOES_NOT_CONTAIN_IGNORE_CASE |
                    CONTAINS_ANY | CONTAINS_NONE | CONTAINS_ALL
String           -> StringSingleQ | StringDoubleQ
StringSingleQ    -> '(char)'
StringDoubleQ    -> "(char)"
StringList       -> [ String (, String)* ]
ValueLiteral     -> [a-zA-Z0-9_.]*
ValueLiteralList -> **[** ValueLiteral (, ValueLiteral)* **]**3
Literal          -> [a-zA-Z0-9_]*
DateRangeLiteral -> TODAY | YESTERDAY | LAST_7_DAYS | THIS_WEEK_SUN_TODAY | THIS_WEEK_MON_TODAY | LAST_WEEK |
                    LAST_14_DAYS | LAST_30_DAYS | LAST_BUSINESS_WEEK | LAST_WEEK_SUN_SAT | THIS_MONTH
Date             -> 8-digit integer: YYYYMMDD

Hinweise

  • 1 FROM ist in Dienstaufrufen nicht zulässig, in Berichtsdownloads hingegen obligatorisch.
  • 2 DURING ist in Dienstaufrufen optional. Die Klausel ist in Berichtdownloads erforderlich, wenn die SELECT-Klausel der Abfrage die Spalte Date oder Week enthält.
  • 3 Bei ValueLiteralList müssen eckige Klammern [ ] verwendet werden. An anderer Stelle kennzeichnen diese einen Bereich.
  • ? bedeutet optional; * steht für ein oder mehrere Vorkommen.
  • Reihenfolge: SELECTFROM...WHERE...DURING...ORDER BY...LIMIT...
  • Bei Keywords muss die Groß-/Kleinschreibung nicht beachtet werden.
  • Bei Spaltennamen und Literalen muss die Groß-/Kleinschreibung beachtet werden.
  • Leerraum spielt keine Rolle.
  • Für Strings werden sowohl Anführungszeichen als auch Apostrophe akzeptiert. Escapesequenzen sind: \", \', \\.

Feedback geben zu...