Field Masks

AI-generated Key Takeaways

• The Ad Manager REST API utilizes field masks, represented as comma-separated field names, for partial data reads and writes to enhance performance.

• Read masks, set via the fields query parameter or X-Goog-FieldMask HTTP header, dictate which fields are returned in API responses, with default masks applied to some methods for efficiency.

• Update masks, specified as query parameters, control which fields are modified during update requests, ensuring only masked fields are affected regardless of the request body content.

• Field masks support traversal using the . character and wildcards for selecting specific fields or all fields within an entity, although wildcard use in update masks is not recommended for forward compatibility.

• Invalid fields in a field mask will trigger an INVALID_ARGUMENT error response from the API.

The Ad Manager REST API uses field masks for partial reads and writes. This can improve performance by limiting the amount of data transferred. Field masks are represented by a comma separated list of field names. For example:

startTime,endTime,targeting.geoTargeting

Read masks

Read masks control which fields are present in an API response. You can set a read mask on your request in two ways:

1. The fields query parameter:

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

2. The X-Goog-FieldMask HTTP header:

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

Note: Both camelCase and snake_case are supported in field mask strings.

Default read masks

Some API methods include a default field mask for fields that are expensive to return. List methods are an example of this. By default, they don't include the totalSize field.

These fields must be explicitly requested in the field mask either by name or by using the * wildcard.

Update masks

Update masks control which fields will be changed in an update (PATCH) request. When an update mask is set, only the fields in the mask will be updated regardless of which fields are set in the request body.

Update masks are set as query parameters. For example:

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

Field traversal

Field masks can specify fields within an entity using the . character for traversal. This is the same syntax used by Filters.

Field masks are always relative to the response object. For example, a mask for reading a LineItem might include primaryGoal.units. The corresponding mask for listing LineItems is lineItems.primaryGoal.units.

You can specify either a field as a whole, or one of its subfields. Both primaryGoal and primaryGoal.units are valid.

This also applies to repeated fields. A LineItem field mask of creativePlaceholders.size is valid and only includes the size field for each CreativePlaceholder.

Note: Field masks don't permit accessing a particular element of a repeated field by index. This results in an INVALID_ARGUMENT error.

Wildcards

Warning: Using a wildcard in an update mask is not forwards compatible. The wildcard will clear any fields that are unknown to your client.

Field masks support the * character which indicates all fields in the message. The following examples demonstrate wildcard usage when listing Orders. This method has a default read mask that does not include the total_size field.

Example	Meaning
*	Includes all fields, including total_size
orders	Includes only the orders field and all its subfields
orders.*	Includes only the orders field and all its subfields

Invalid fields

If a field mask refers to a value that doesn't exist, the API will respond with an INVALID_ARGUMENT error.