Feldmasken

In der Ad Manager REST API werden Feldmasken für teilweise Lese- und Schreibvorgänge verwendet. Dies kann die Leistung zu verbessern, indem die übertragene Datenmenge begrenzt wird. Feldmasken werden durch eine durch Kommas getrennte Liste von Feldnamen dargestellt. Beispiel:

startTime,endTime,targeting.geoTargeting

Masken lesen

Mit Lesemasken wird gesteuert, welche Felder in einer API-Antwort vorhanden sind. Sie können eine können Sie die Maske auf zwei Arten für Ihre Anfrage lesen:

  1. Der Abfrageparameter fields:

    curl https://admanager.googleapis.com/v1/networks/123456/adUnits?fields=adUnits,nextPageToken,totalSize

  2. Der HTTP-Header X-Goog-FieldMask:

    curl -H "X-Goog-FieldMask: adUnits,nextPageToken,totalSize" \
    https://admanager.googleapis.com/v1/networks/123456/adUnits

Standard-Lesemasken

Einige API-Methoden enthalten eine Standardfeldmaske für teure Felder. zurück. Listenmethoden sind ein Beispiel dafür. Standardmäßig enthalten sie keine totalSize ein.

Diese Felder müssen in der Feldmaske explizit angefordert werden, entweder über den Namen oder durch mithilfe des Platzhalters *.

Masken aktualisieren

Mit Aktualisierungsmasken wird gesteuert, welche Felder bei einer Aktualisierung geändert werden (PATCH) Wenn eine Aktualisierungsmaske festgelegt ist, werden nur die Felder in der Maske aktualisiert unabhängig davon, welche Felder im Anfragetext festgelegt sind.

Aktualisierungsmasken werden als Abfrageparameter festgelegt. Beispiel:

curl -X PATCH https://admanager.googleapis.com/v1/networks/1234/order/4567?updateMask=displayName

Field Traversal

Feldmasken können Felder innerhalb einer Entität angeben, indem das Zeichen . für Durchlaufs. Dies ist dieselbe Syntax, die auch von Filter:

Feldmasken sind immer relativ zum Antwortobjekt. Eine Maske für Lesen eines LineItem kann primaryGoal.units enthalten. Die entsprechende Maske für Einträge LineItems ist lineItems.primaryGoal.units.

Sie können entweder ein Feld als Ganzes oder eines seiner Unterfelder angeben. Beide primaryGoal und primaryGoal.units sind gültig.

Dies gilt auch für wiederkehrende Felder. Eine LineItem-Feldmaske von creativePlaceholders.size ist gültig und enthält nur das Feld size pro CreativePlaceholder.

Platzhalter

Feldmasken unterstützen das Zeichen *, mit dem alle Felder in der Nachricht gekennzeichnet werden. Die folgenden Beispiele veranschaulichen die Verwendung von Platzhaltern beim Eintragen Orders Diese Methode hat eine Standard-Lesemaske, die Feld total_size nicht enthalten.

Beispiel Bedeutung
* Enthält alle Felder, einschließlich total_size
orders Enthält nur das Feld orders und alle untergeordneten Felder
orders.* Enthält nur das Feld orders und alle untergeordneten Felder

Ungültige Felder

Wenn sich eine Feldmaske auf einen Wert bezieht, der nicht vorhanden ist, antwortet die API. mit dem Fehler INVALID_ARGUMENT.