google api update —— from AdWords API to Google Ads API
|
You’re receiving this email because the developer token associated with this email address has recently made requests to the legacy AdWords API which will be sunsetting on April 27, 2022. |
|
Next steps
|
Get support
If you have any questions about upgrading, please don't hesitate to contact us
on the forum or at googleadsapi-support@google.com.
https://developers.google.com/google-ads/api/docs/migration
New and Improved in the Google Ads API
The Google Ads API introduces new features and improvements when upgrading from the AdWords API. This page details some of the highlights of those improvements. For a more detailed list of changes in the Google Ads API, see the release notes.
Key points
Innovation: Extending our innovative ad platform
Expect more frequent releases with additional features and improved upwards compatibility. The many new features such as automated recommendations to help increase campaign performance, are just the start of our efforts to provide an innovative and full-featured advertising API. With more frequent releases, the Google Ads API can roll out new features and bug fixes more often.
Productivity: Faster, easier to build applications
The Google Ads API simplifies building applications with less code, making time to market faster for applications. There’s seamless integration between reports and updates, along with a flexible and intuitive query language for scalable reporting. This update makes the API consistent with Google's latest standards.
The legacy AdWords API will be shutdown in April 2022
September 2018 was the last release of the AdWords API. As announced in April 2021, the AdWords API will sunset April 27, 2022. As a result, new features will only appear in the Google Ads API, and there may be deprecations in the AdWords API, such as feed-based extensions.
Resource mappings
https://developers.google.com/google-ads/api/docs/migration/mapping?hl=en
https://developers.google.com/google-ads/api/docs/reporting/overview
AWQL 变为 GAQL
AWQL：
https://developers.google.com/adwords/api/docs/guides/awql
GAQL：
https://developers.google.com/google-ads/api/docs/query/overview
https://developers.google.com/google-ads/api/docs/migration/mapping?hl=en
https://developers.google.com/google-ads/api/docs/migration/querying
https://developers.google.com/google-ads/api/docs/migration/workflow
Reports in the Google Ads API do not return plain text or XML. Instead, the GoogleAdsService Search and SearchStream methods return GoogleAdsRows that contain objects.
https://developers.google.com/google-ads/api/docs/migration/format-specs
Customer ID format
In the AdWords API, you could specify your customer ID either as a 10-digit number or a string in the format XXX-XXX-XXXX. Now, in the Google Ads API, you must specify your Customer ID as a 10-digit number without dashes.
Response format
In the AdWords API, searching for and fetching fields for entities was one and the same, but that is no longer the case in the Google Ads API. The difference in request parameters also results in a difference in response formats for the two actions.
When searching using the GoogleAdsService, responses will include one GoogleAdsRow for each entity that matched your search parameters. Each row contains one object, for example a campaign, and the only fields populated on this object are the fields that you specifically requested in your query.
When fetching using a specific service, say CampaignService, you can only request a single entity at a time by resource name, and all fields for that entity will be populated in the response.
https://developers.google.com/google-ads/api/docs/migration/overview
Overview
With the unification of reporting and queries, you no longer need to define a report. You can directly query resources for data using a SearchGoogleAdsStreamRequest or a SearchGoogleAdsRequest.
Start your report migration planning by consulting the appropriate field mapping tables. These tables show the AdWords API field name and its equivalent in the Google Ads API.
https://developers.google.com/google-ads/api/docs/migration/mapping
https://developers.google.com/google-ads/api/docs/migration/query-migration-tool
SELECT Date,RegionCriteriaId,CityCriteriaId,CountryCriteriaId,CampaignId,CampaignName,Device, AdGroupId, AdGroupName,Impressions, Clicks, Cost,Conversions,AccountTimeZone,AllConversionValue FROM GEO_PERFORMANCE_REPORT DURING 20211101,20211112 SELECT segments.date, segments.geo_target_region, segments.geo_target_city, campaign.id, campaign.name, segments.device, ad_group.id, ad_group.name, metrics.impressions, metrics.clicks, metrics.cost_micros, metrics.conversions, customer.time_zone, metrics.all_conversions_value FROM geographic_view WHERE segments.date BETWEEN "2021-11-01" AND "2021-11-12" WARNING: The GEO_PERFORMANCE_REPORT returned data for both user location criteria and geographic targets. The Google Ads API provides this information in two separate resources: user_location_view and geographic_view.
https://developers.google.com/google-ads/api/docs/migration/url-reports
https://developers.google.com/google-ads/api/docs/migration/types
https://developers.google.com/google-ads/api/docs/migration/micro-migration/part-0
Similarly for the Google Ads client libraries:
Maven (Java)
Nuget (.NET)
https://www.nuget.org/packages/Google.Ads.GoogleAds/
CPAN (Perl)
Composer (PHP)
PyPi (Python)
Ruby Gems (Ruby)Once you've successfully completed the installation steps described above, you’re ready to proceed. To verify that your setup is correct, try executing the Get Campaigns example.
https://developers.google.com/google-ads/api/docs/migration/micro-migration/part-2
https://developers.google.com/google-ads/api/docs/migration/micro-migration/part-3
https://developers.google.com/google-ads/api/docs/migration/micro-migration/part-4
All reports in the Google Ads API go through the SearchStream and Search methods on the GoogleAdsService. These methods accept a GAQL string that specifies which resources should be retrieved, how they should be segmented, filtered, and ordered. The SearchStream and Search methods are also the recommended way to retrieve individual entities from the API.
In the AdWords API, you would use a GET method, for example, CampaignService.get. There are GET methods in the Google Ads API as well, but they're meant only for testing and debugging.
The Google Ads API reporting interface is the same whether you want to retrieve resource attributes or performance data for entities, and in most cases you can retrieve this information with a single query.
When migrating a report from the AdWords API, start with the Report migration guide. It contains a query migration tool that converts AWQL queries into GAQL queries that you can pass into a search request. There's even a page that maps each AdWords report Google Ads resources and fields.
https://developers.google.com/google-ads/api/docs/migration/micro-migration/part-5
In this script we'll use the SearchStream method, but it's possible to achieve the same functionality with the Search method. Add a new method that we can reuse throughout this script that accepts a GAQL query and returns the first GoogleAdsRow in the response.
