[go: nahoru, domu]

Today we're releasing v3.5 of the Campaign Manager 360 API (previously DCM/DFA Reporting and Trafficking API). Highlights of this release include:

Details of these and all other changes are covered in our release notes.

Deprecation and sunset reminderIn accordance with our deprecation schedule, this release marks the beginning of the depreciation period for v3.4, which will sunset on Dec 24, 2021. After this date, any requests made against v3.4 will begin returning errors.

As a reminder, Campaign Manager 360 API v3.3 will sunset on June 30th, 2021. After this date, all requests made to v3.3 of this API will fail. If you're still using this version, you must migrate to the most current release to avoid an interruption in service.

See the migration guide for details. For most, migrating will be as easy as adopting the latest version of your preferred client library. However, all users are advised to review the release notes to learn about important version differences you may need to be aware of.

If you have questions about this or anything else Campaign Manager 360 API related, feel free to reach out to us on our support forum.

Learn MoreAs with every new version of the Campaign Manager 360 API, we encourage you to carefully review all changes in the release notes. For those of you looking to get going right away, updated client libraries are now available. If you're just starting out, the Get Started guide is a great reference to help you get up and running quickly.


Give it a try and let us know if you have any questions!

The Google Ads API Developer Relations team will be hosting a live webinar covering Error Handling, Retry, and Timeouts, on June 3 at 10 AM EST (2 PM GMT).

AgendaThe webinar will cover the topics below and include code walkthroughs to demonstrate how to perform different actions with the Google Ads API client libraries. We will also host a Q&A at the end with members of the Google Ads Developer Relations and Engineering teams.
  • Types of errors returned by the Google Ads API
  • Catching and deciphering Google Ads API errors
  • Identifying failed operations using partial failure mode
  • Setting HTTP timeouts
  • Best practices for retrying failed requests
PrerequisitesIn order to get the most out of this webinar, we suggest you develop a basic understanding of the Google Ads API. To learn more, please visit our API Overview documentation or check out this Google Ads API Overview workshop from 2019. In addition, we strongly recommend that you install and configure one of our client libraries to follow along with the live coding examples.

RemindersFeel free to add the event to your calendar. In addition, you can set a reminder for the event on YouTube by clicking the “Set reminder” button on the YouTube event page.

We look forward to sharing our knowledge of the Google Ads API with you and answering your questions. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.


Today we’re releasing an update to the Display & Video 360 API which includes the following features:

More detailed information about this update can be found in the Display & Video 360 API release notes. Before using these new features, make sure to update your client library to the latest version.

We also recently published a collection of code samples on GitHub. The samples, available in Python, Java, and PHP, demonstrate how to interact with the Display & Video 360 API using the available client libraries.
If you run into issues or need help with these new features or samples, please contact us using our support contact form.

This blog series follows the journey of building the new and improved Interactive Google Ads Query Builder tool. If you’ve read this entire series up to this point, you should understand many details and nuances of the Google Ads Query Language (GAQL). Part 8 will wrap up our journey and discuss what we’ve learned along the way.

Creating the User InterfaceWith the ResourceService, SelectionService, and ValidationService in place, all that is left to do is create the components that will comprise the user interface. In some cases, we can pull data directly from our services. In other cases, such as tracking selectability, selection status, or query validity, we can subscribe to our services so that the components always reflect the current state of the application.

ConclusionThis blog series has walked through several integral parts of the Query Builder application with an emphasis on those which can be useful in understanding GAQL. Let’s recap our learnings from each post:


Part 1 - Setting the Stage

Part 2 - Designing a Resource Schema
  • What a schema might look like for our application.

Part 3 - Creating a Resource Schema
  • How to use the GoogleAdsFieldService to retrieve field metadata.
  • Field compatibility in GAQL.
  • The REST discovery API.

Part 4 - Creating the Resource Service
  • GAQL query structure.
  • The various types of fields that can appear in GAQL clauses.
  • Field properties and how they correspond to different GAQL clauses.

Part 5 - Determining Field Selectability
  • Field compatibility and how to determine if a field is selectable.

Part 6 - Selecting and Deselecting Fields
  • GAQL query structure.
  • Additional detail regarding selectability.
  • Using Observables in Angular.

Part 7 - Query Validation
  • The various facets of GAQL query validation.
BonusIn addition to everything we’ve learned about the Google Ads Query Language, I hope you’ve also picked up some tips about writing Angular applications. This was my first time using Angular, and I’ve found it to be a powerful framework for quickly building complex applications. Using Angular services with dependency injection along with observables has been an efficient way to manage app-wide state.


Hopefully this series deepened your understanding of how to construct GAQL queries with the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

Today we are launching a new feature in Content API for Shopping v2.1: products.update.
The products.update method allows you to submit a subset of changes for a given product using the Products API. It works similarly to products.insert, but only requires the fields you would like to modify.

Users of inventory.set in Content API v2, will be familiar with the ability to provide updates to price, availability and other limited fields. The products.update method goes one step further and allows you to modify any fields that are mutable with products.insert. Users that are migrating from v2 to v2.1 ahead of the September 30, 2021 sunset date, might find this new functionality useful.

Products.update utilizes the HTTP PATCH method. Here is an example of updating the salePrice using REST:

HTTP request:

PATCH https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}


Example request body:
{
  "salePrice": {
    "value": "17.99",
    "currency": "USD"
  }
}

You can also provide product update operations as part of a products.custombatch request. For more examples and use-cases, see the products.update guide in the documentation.

If you require further support using this feature, please visit the Content API for Shopping forum.


This blog series follows the journey of building the new and improved Interactive Google Ads Query Builder tool. Part 6 of this series described how we select and deselect fields from a query. In Part 7, we will discuss how to validate queries based on user selections.

Background
While we’ve learned about field compatibility in Part 5 and a bit more about selectability in Part 6, it is still possible to create an invalid Google Ads Query Language (GAQL) string using the Query Builder. In order to account for this, we’ll create a ValidationService that subscribes to the Observable we created in the SelectionService in Part 6. Each time the Observable is triggered, we’ll perform a set of validation tests and generate a list of error messages. We’ll create another Observable in the ValidationService that is emitted each time the validations are run. This way, we can let users know if their query contains any errors. If the user hasn’t made any selections, this represents the initial state of the application, so we won’t show any errors in this case.





We will perform the following validation tests:
  • Ensure the SELECT clause contains fields
  • Ensure core date selections are valid
  • Ensure click_view has a valid date filter
  • Ensure change_event and change_status have valid date filters
  • Ensure change_event and change_status have valid limits

Ensure the SELECT Clause Contains FieldsA valid GAQL query must contain at least one valid field in the SELECT clause. If selections have been made in clauses other than SELECT, and the SELECT clause is empty, we will generate an error.

Ensure Core Date Selections are ValidIf there exists a core date segment (segments.date, segments.week, segments.month, segments.quarter, segments.year) in any clause of a query, then the filtering conditions in the WHERE clause must combine to form a finite date range of core date segments that, in aggregate, form a date range of at least one day. If there are no core date segments present in the query, we will not generate an error.


Otherwise, we’ll ensure that the core date segment filters in the WHERE clause combine to form a finite range. In other words, a single filter such as WHERE segments.date > ‘2021-01-01’ would fail because the date range is open ended, in which case we’ll generate an error. However, the following filters would be valid: WHERE segments.date > ‘2021-01-01’ AND segments.date < ‘2021-02-01’, WHERE segments.date = ‘2021-01-01’, and WHERE segments.date DURING LAST_7_DAYS. All three examples have a beginning and end date, so we will generate no error.


Finally, if the core date segment filters do form a finite range, we’ll check to ensure that, in aggregate, they result in at least a single day. For example, a query containing the following filtering conditions will fail because no dates meet both filtering criteria: WHERE segments.date = ‘2021-01-01’ AND segments.date BETWEEN ‘2021-02-01’ AND ‘2021-03-01’, in which case we will generate an error. However, this filtering condition is valid: WHERE segments.date BETWEEN ‘2021-01-01’ AND ‘2021-01-31’ AND segments.date >= ‘2021-01-15’ AND segments.date < ‘2021-03-01’ because the date range of ‘2021-01-15’ - ‘2021-01-31’ meets all filtering criteria, and therefore, we will generate no error.

Ensure click_view has a Valid Date FilterWhen click_view is the main resource in the FROM clause, a date filter specifying a single day in the last 90 days must be present in the WHERE clause regardless of what other selections have been made.
Ensure change_event and change_status have Valid Date FiltersIf either change_event or change_status is the resource in the FROM clause, there must be a valid, finite date range composed of filtering criteria in the WHERE clause similar to the rule Ensure Core Date Selections are Valid. However, this criteria applies regardless of whether or not any date fields are present in the query. In addition, the filtering conditions are not composed of core date segments because none of the core date segments are available when change_event or change_status is the main resource in the FROM clause (see Part 4). When change_event is the resource in the FROM clause, date evaluation on the Google Ads API server is performed on filters on the change_event.change_date_time field. When change_status is the resource in the FROM clause, date evaluation on the Google Ads API server is performed on the change_status.last_change_date_time field.
Ensure change_event and change_status have Valid LimitsIf either change_event or change_status is the resource in the FROM clause, the query must contain a valid limit, or a positive integer.
ConclusionWe have now created a ValidationService that checks for errors in a GAQL query. Each time a GAQL string changes, we’ll run these checks, generate a list of errors, and emit an event from the Observable in our ValidationService. In the component that subscribes to this Observable, we’ll show an error icon for a non-empty error list. In this post, we’ve covered the various facets of GAQL query validation.


Hopefully this has deepened your understanding of constructing GAQL queries with the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

As announced previously, the Ad Exchange Buyer API is set to sunset by the end of Q2, 2021. We will begin the process of phasing the API out on June 1st, where a small percentage of API requests will begin to return an API error response that includes details about the impending sunset. You can expect API errors to progressively increase leading up to the sunset date. Note that this sunset does not include the Ad Exchange Buyer II API, which is not deprecated at this time.

The Real-time Bidding API is the replacement for the Ad Exchange Buyer API, and we encourage you to migrate before the sunset date in order to avoid interruptions to your integration. To learn more about the Real-time Bidding API, you can read the migration guide, reference documentation, and the new resource guides. Additionally, samples for several programming languages are available to assist you with your migrations.

If you encounter any issues, or have any questions we can assist with, please contact us via our support forums.

We're happy to announce that v202105 of the Google Ad Manager API is available starting today. With this release, Creative Previews are going mobile! You can now push creatives to multiple linked devices using the new LineItemCreativeAsociationService.pushCreativeToDevices method and Linked_Device PQL table.

This release also brings support for pause controls for programmatic proposals and new ReportService features like Inventory Share dimensions.


For the full list of changes for v202105 and all other active API versions, check the release notes. Feel free to reach out to us on the Ad Manager API forum with any API-related questions.

This blog series follows the journey of building the new and improved Interactive Google Ads Query Builder tool. Part 5 of this series described how we determine whether or not a field is selectable. In Part 6, we will discuss how we add fields to a Google Ads Query Language (GAQL) string using the SelectionService.

GAQL String StateIn order to track which fields have been selected, we need to keep track of the GAQL string’s state, which we can do in an instance variable called selectedFields that has the following interface definition:


interface SelectedFields {
select: string[];
where: Array<{field: string, context: string}>;
orderBy: Array<{field: string, context?: string}>;
limit?: string;
params?: string;
}



The select field holds an array of field names. The where field holds an array of objects, each of which contains a field name and context string. By context, we mean the filtering condition to apply to the field (or operator and operand). For example, if we added the filtering condition, ad_group.id = 1234567890 to the WHERE clause, the field would be ad_group.id, and the context would be = 1234567890. Similarly, the orderBy field holds an array of field names and optional context strings. Here, context is the optional ASC or DESC direction (default ASC). The limit field is the optional string representation of the integer LIMIT. Finally, the optional params field represents the optional string value of the PARAMETERS clause. We don’t need an array here because there is currently only a single option for this clause.
Selecting FieldsNow that we have a data structure in place to track the state of a user’s query, we can implement a method to select a field in any clause.


selectField(field: string, clause: string, context?: string): void {
...
}

If the clause is SELECT, we’ll add the provided field to the select array in selectedFields. When users add a field in the SELECT clause, no context is provided.


If the clause is WHERE, all three parameters are required because a filtering condition containing an operator and operand must be provided as a context string. When users click the checkbox to add a field in the WHERE clause, we’ll open a dialog prompting them to specify the operator, and then an operand once the operator has been set. Depending on the data_type of the field being selected, we’ll pre-populate the list of available operators a user can select, and depending on the operator selected, we’ll show the user a different component to input the operand. Once a user adds the filtering criteria, we’ll join the operator and operand into a single string to create the context string.





If the clause is ORDER BY, context is optional. When a user selects a field in the ORDER BY clause, we’ll call selectField without any context and add the field to the orderBy array of selectedFields without any context. We’ll also present users with radio buttons under the field name to specify an order of ASC or DESC. Upon clicking one of the options, we’ll update the respective field’s entry in the orderBy array to add the order context.




If the clause is LIMIT or PARAMETERS, we’ll update the limit and params entries of selectedFields, respectively, with the provided string as the field parameter. The limit must be a positive integer, the validation for which is performed in the related UI component. The only parameter currently available is include_drafts, and the default value is false. Therefore, we’ll present users with a checkbox in the UI component for PARAMETERS with a single option ‘include_drafts=true’. If the user clicks the checkbox, we’ll pass the string include_drafts=true to selectField as the field.
SELECT PresenceWhile the logic of selecting fields is straight-forward, there are two rules regarding selectability that we intentionally skipped in part 5. Certain fields must be present in the SELECT clause before they can be inserted into the WHERE or ORDER BY clauses.



Rule #1: with the exception of “core date segments” (segments.date, segments.week, segments.month, segments.quarter, segments.year), all segments and segmenting resources must be present in the SELECT clause before they can be inserted into the WHERE clause.



Rule #2: all segments, segmenting resources, metrics, and attributed resource fields must be present in the SELECT clause before they can be inserted into the ORDER BY clause. In other words, only fields on the resource in the FROM clause can be placed in the ORDER BY clause without first being inserted into the SELECT clause.


In these cases, we’ll present a dialog that enables the user to add the field to the SELECT clause as well as the desired clause in a single step.





Deselecting FieldsIn order to deselect fields, we’ll implement a method in the SelectionService called deselectField.


deselectField(field: string, clause: string): void {

}




Deselecting a field is similar to selecting a field. As a safeguard, we’ll first check if the field is selected. Then, if the clause is SELECT, WHERE, or ORDER BY, we’ll remove the deselected field from the respective array entry of selectedFields. In the event the field that is required to be present in SELECT before being added to WHERE or ORDER BY according to the rules described above and is removed from SELECT, we’ll automatically remove the field from SELECT in a single operation. If the clause is LIMIT or PARAMETERS, we’ll update the respective entry of selectedFields to undefined.
Updating the OutputWith the selectedFields variable, selectField method, and deselectField method in place, we can now track the state of the query string. In order to keep track of changes throughout the application, we’ll create an Observable in the SelectionService and call next on it each time selectField or deselectField is called. Then, we can subscribe to the observable in any component that needs to be aware of the GAQL query state.
ConclusionWe have now updated the SelectionService to select fields and deselect fields. In this post, we’ve covered:
  • GAQL query and clause structure.
  • Additional detail regarding selectability.
  • Using Observables in Angular.
Hopefully this has deepened your understanding of constructing GAQL queries with the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.

Google Ads has recently introduced Asset-based extensions. This new paradigm reduces the complexity of managing extensions when compared to the existing Feed-based extensions. Asset-based extensions will only be supported in Google Ads API.

Asset-based extensions will replace the current Feed-based extensions. All existing Feed-based extensions will automatically migrate in two batches. Other services that use Feeds, such as Location extensions, Dynamic Ads, and Page Feeds, will be discussed in future announcements.

Extension
Type
Asset
Available to
Test
Accounts
Asset
Available to
Production
Accounts
Auto
Migration
Date
Feeds
Sunset
Date
Lead Form Google Ads API v6 Google Ads API v6 October 20, 2021 February 15, 2022
Promotion Google Ads API v7 Google Ads API v7 October 20, 2021 February 15, 2022
Callout
Sitelink
Structured Snippet
Google Ads API v7 Google Ads API v8
(tentative)
October 20, 2021 February 15, 2022
App
Call
Hotel Callout
Image
Price
Google Ads API v9
(tentative)
Google Ads API v9
(tentative)
February 15, 2022 April 8, 2022


What do I need to do?
You should migrate any Feed-based extensions and related code that you intend to continue to use to Asset-based extensions as soon as is feasible. You should remove Feed-based extensions after migrating; for a given extension type, any Asset-based extensions will serve instead of Feed-based extensions. See our extensions migration guide for details. Consider developing and testing your Asset-based extension implementation using a test account so as to access all the currently available Asset types.

After the automatic migration dates, you will no longer be able to create or mutate Feed-based extensions in the AdWords API or the Google Ads API. Feed-based extensions will no longer generate new data. You will still be able to issue Feed-related report queries until August 2022; thereafter all Feed-based extension data will be removed and report queries will return errors.

What if the October date is too soon?
You can request to opt individual accounts out of the October auto migration; the process for doing so will be announced in a subsequent blog post. Note that the Feed-based extensions in the first batch will still become unavailable for all accounts in February 2022.

If you have any questions, concerns, or feedback, please contact us via our forum.

On Tuesday, June 1, 2021, in accordance with the deprecation schedule, v202005 of the Ad Manager API will sunset. At that time, any requests made to this version will return errors.

If you’re still using v202005, now is the time to upgrade to a newer release and take advantage of additional functionality. For example, in v202102 we added support for AudioCreative types.

When you’re ready to upgrade, check the full release notes to identify any breaking changes. For instance, starting in v202008, we replaced the singular LineItem.viewabilityProviderCompanyId field with viewabilityProviderCompanyIds for specifying a list of IDs.

As always, don't hesitate to reach out to us on the developer forum with any questions.

Starting June 10, 2021, the Placement Performance Report for the AdWords API and Google Ads scripts will exclude automatic placements according to data retention policy changes. Afterwards, the Placement Performance Report will only contain the data for managed and excluded placements at the ad group level.

What's changing?
The schema (attributes, segments and metrics) of the Placement Performance Report will remain the same, but only the data for managed and excluded placements will be available. The data for automatic placements that have not been explicitly targeted will be removed from this report, and queries for the automatic placements data (WHERE Id = 0) from this report will return empty results.

Who will be impacted?
All developers that access the Placement Performance Report using the AdWords API or Google Ads scripts today for automatic placements reporting will be affected.

What should you do?
Before June 10, 2021, review and modify the reporting queries in your AdWords API and Google Ads scripts applications to use the Automatic Placement Performance Report instead for automatic placements reporting.

If you have any questions or need additional help, contact us through the Google Ads API and AdWords API forum or at googleadsapi-support@google.com.

This blog series follows the journey of building the new and improved Interactive Google Ads Query Builder tool. Part 4 of this series described how we created a ResourceService to display relevant fields given the resource in our FROM clause based on a user’s location in the app. In Part 5, we will discuss how to determine whether a field is selectable or not in a Google Ads Query Language (GAQL) query string.
Background & ObjectiveThe determination of whether a field is selectable, or can be added to a clause of GAQL string, is dependent on both: 1) inherent properties of the main resource in the FROM clause and its fields’ properties as well as 2) the current state of the GAQL query string. The ResourceService we created in Part 4 addresses item (1) because users will only be shown fields that are able to be selected based on those inherent properties.

In order to address item (2), we will create a new service called the SelectionService. The responsibilities of this service will include determining selectability, selecting fields, and deselecting fields. We will discuss determining field selectability in this post, and in Part 6 of this series, we’ll discuss how the SelectionService selects and deselects fields.
Field CompatibilityNot all fields are compatible with each other. When two fields are compatible, both can be present in a GAQL string. If two fields are incompatible, only one of the two fields may be present in any clause of a GAQL string at a time. Therefore, if there is a field in the GAQL string that is incompatible with the field being evaluated, the field being evaluated is not selectable, and the UI will reflect this by presenting users with a corresponding error message.





Implementation
We will keep track of selected incompatible fields for each field on the main resource with an instance variable called incompatibleSelected that maps each field to a Set of its incompatible fields that have been selected.

interface IncompatibleSelected: {[key: string]: Set<string>}


We’ll initialize this incompatibleSelected such that the keys of the map are the aggregated list of fields on the resource, as determined by the ResourceService, and the value of each entry is an empty Set.

Each time a field is selected, we will add the selected field to the incompatibleSelected Set of each field that is incompatible with the selected field. For example, let’s assume that ad_group is the resource in our FROM clause. segments.ad_destination_type is incompatible with metrics.absolute_top_impression_percentage and metrics.active_view_cpm, among other fields. The table below illustrates the incompatibility relationship among these fields.
Field Incompatible Fields
segments.ad_destination_type [metrics.absolute_top_impression_percentage, metrics.active_view_cpm, …]
metrics.absolute_top_impression_percentage [segments.ad_destination_type, …]
metrics.active_view_cpm [segments.ad_destination_type, …]
If segments.ad_destination_type is selected, we’ll add segments.ad_destination_type to the entries for metrics.absolute_top_impression_percentage and metrics.active_view_cpm in the incompatibleSelected map.

Following the addition of segments.ad_destination_type to any clause in our query, a subset of our incompatibleSelected field would look like this.

incompatibleSelected = {

'segments.ad_destination_type': {},
'metrics.absolute_top_impression_percentage': {'segments.ad_destination_type'}
'metrics.active_view_cpm': {'segments.ad_destination_type'}
...
}


Each time a field is deselected, we’ll first check if that field is present in any clause of the query (more detail to be provided in Part 6) because if so, incompatibleSelected should not be updated. For example, if segments.ad_destination_type had been selected in the SELECT and ORDER BY clauses, but was only deselected from ORDER BY, we don’t want to make any adjustments to the incompatibleSelected map because segments.ad_destination_type is still present in the query. However, if the deselected field is absent from all clauses, we’ll delete the deselected field from the Set for each field that is incompatible with the deselected field.

In our example, let’s assume we now deselect segments.ad_destination_type from the SELECT clause, and it is no longer present in the query. Now, we’ll remove this field from the metrics.absolute_top_impression_percentage and metrics.active_view_cpm entries of the incompatibleSelected map. At this point, every entry in the incompatibleSelected map would contain an empty Set.


With this data structure in place, we can create a method called isSelectable that accepts a field name as a parameter. isSelectable returns true if the Set for the field in incompatibleSelected is empty and false if it is not.


  isSelectable(field: string): boolean {
return this.incompatibleSelected[field]?.size === 0;
}

ConclusionWe have now implemented logic into a SelectionService that determines whether a field is selectable. As we display each field to users, we can simply call isSelectable(field) to determine what to show users in the UI. In this post we’ve covered field compatibility and how it relates to whether or not a field is selectable. In Part 6, we’ll build on this section to see how we can select fields, deselect fields, and keep track of the state of the GAQL query string with the SelectionService.

Hopefully this deepened your understanding how to construct GAQL queries using the Google Ads API. If you have any questions or need additional help, contact us via the forum or at googleadsapi-support@google.com.