Page Summary
-
Change Status tracks which resources have changed within an account over a given time period, returning only the latest change if a resource changed multiple times.
-
Change Status provides a list of changed resources that can be filtered by date and resource type, indicating if a resource was ADDED, CHANGED, or REMOVED.
-
You can determine the resource type from the
resource_nameeven if theresource_typeis UNKNOWN in earlier API versions. -
The
last_change_date_timefield shows the time of the most recent change and can be used to compare with local data for freshness. -
To get the current values of a changed resource, you need to perform a new query using the
resource_nameretrieved from Change Status.
ChangeStatus
provides a means to keep track of
which resources have changed within an account over a given time period. If
a resource had multiple changes during your given time period, then only
the latest change is returned. You can then determine if you need to sync your
local database values with those that have changed within the time period.
For example, if during a given time period you add and then update a given
campaign, only the change status for the UPDATE
and not for the ADD
operation is returned. If you move the end of the timeframe to before the
update, then you would see the ADD
operation.
If you want the complete field-by-field results with a detailed view, see ChangeEvent
.
Understand the scope of reported changes
When ChangeStatus
indicates a change to a resource, such as a CAMPAIGN
, this means that either the resource itself
or one of its subordinate resources—an ad group, ad, or criterion within
that campaign—has been modified.
The ChangeStatus
resource aims to provide a broad overview of which parts
of your account have seen activity. If a change occurs in a child resource, the
parent resource's ID might be returned to ensure that no modifications are
missed. This is particularly true for resource types not explicitly listed in
the ChangeStatusResourceType
enum.
For example, while a modification to an ad group bid modifier flags the AdGroupBidModifier
resource type, a change
to a less granular or newer child entity might flag the parent Campaign
or AdGroup
instead.
To obtain field-level details about what exactly changed, you can use the ChangeEvent
resource, which provides a more
detailed view of creations and updates.
Change Status types
The following resource types
are
tracked. Note that the resource type IDs are different than the enum value
indexes of ChangeStatusResourceType
.
Determine resource type by ID
The Google Ads API can return rows with an UNKNOWN
resource type value for earlier
API versions, meaning that the type is supported in a future version of the
Google Ads API but was not fully supported at the time that your current version was
released. When this happens, you can still determine the resource type of the
row by parsing the returned resource_name
.
The resource name format is:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
There could be one or more additional IDs, separated by the -
character, but
the one that is relevant is the resource_type_id
—the second ID after
the final slash. The previous table lists all of the resource type IDs.
Retrieve changes
The list of changes can be filtered by date as well as by resource type. The
operation on a given resource is one of ADDED
, CHANGED
, or REMOVED
.
You can retrieve the list of all changes for all resource types. The returned resource_type
is the field that changed. Any parent fields are also
populated. For example, if the ad_group_criterion
changed, then the ad_group
field is also populated.
A change could take up to 3 minutes to be reflected in the change status results.
The query must filter on a date within the past 90 days, and optionally a time,
and must include a LIMIT
clause set to at most 10,000 results.
Java
private void runExample ( GoogleAdsClient googleAdsClient , long customerId ) { String query = "SELECT change_status.resource_name, " + "change_status.last_change_date_time, " + "change_status.resource_status, " + "change_status.resource_type, " + "change_status.ad_group, " + "change_status.ad_group_ad, " + "change_status.ad_group_bid_modifier, " + "change_status.ad_group_criterion, " + "change_status.campaign, " + "change_status.campaign_criterion, " + "FROM change_status " + "WHERE change_status.last_change_date_time DURING LAST_14_DAYS " + "ORDER BY change_status.last_change_date_time " + "LIMIT 10000" ; try ( GoogleAdsServiceClient client = googleAdsClient . getLatestVersion (). createGoogleAdsServiceClient ()) { SearchPagedResponse response = client . search ( String . valueOf ( customerId ), query ); for ( GoogleAdsRow row : response . iterateAll ()) { Optional<String> resourceNameOfChangedEntity = getResourceNameForResourceType ( row . getChangeStatus ()); System . out . printf ( "On '%s', change status '%s' shows a resource type of '%s' " + "with resource name '%s' was '%s'.%n" , row . getChangeStatus (). getLastChangeDateTime (), row . getChangeStatus (). getResourceName (), row . getChangeStatus (). getResourceType (). name (), resourceNameOfChangedEntity . orElse ( "" ), row . getChangeStatus (). getResourceStatus (). name ()); } } }
C#
public void Run ( GoogleAdsClient client , long customerId ) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client . GetService ( Services . V22 . GoogleAdsService ); string searchQuery = @" SELECT change_status.resource_name, change_status.last_change_date_time, change_status.resource_type, change_status.campaign, change_status.ad_group, change_status.resource_status, change_status.ad_group_ad, change_status.ad_group_criterion, change_status.campaign_criterion FROM change_status WHERE change_status.last_change_date_time DURING LAST_14_DAYS ORDER BY change_status.last_change_date_time LIMIT 10000" ; // Create a request that will retrieve all changes. SearchGoogleAdsRequest request = new SearchGoogleAdsRequest () { Query = searchQuery , CustomerId = customerId . ToString () }; try { // Issue the search request. PagedEnumerable<SearchGoogleAdsResponse , GoogleAdsRow > searchPagedResponse = googleAdsService . Search ( request ); // Iterate over all rows in all pages and prints the requested field values for the // campaign in each row. foreach ( GoogleAdsRow googleAdsRow in searchPagedResponse ) { Console . WriteLine ( "Last change: {0}, Resource type: {1}, " + "Resource name: {2}, Resource status: {3}, Specific resource name: {4}" , googleAdsRow . ChangeStatus . LastChangeDateTime , googleAdsRow . ChangeStatus . ResourceType , googleAdsRow . ChangeStatus . ResourceName , googleAdsRow . ChangeStatus . ResourceStatus , SpecificResourceName ( googleAdsRow . ChangeStatus . ResourceType , googleAdsRow )); } } catch ( GoogleAdsException e ) { Console . WriteLine ( "Failure:" ); Console . WriteLine ( $"Message: {e.Message}" ); Console . WriteLine ( $"Failure: {e.Failure}" ); Console . WriteLine ( $"Request ID: {e.RequestId}" ); throw ; } } /// <summary> /// Return the name of the most specific resource that changed. /// </summary> /// <param name="resourceType">Type of the resource.</param> /// <param name="row">Each returned row contains all possible changed fields</param> /// <returns>The resource name of the changed field based on the resource type. /// The changed field's parent is also populated, but is not used.</returns> private string SpecificResourceName ( ChangeStatusResourceType resourceType , GoogleAdsRow row ) { string resourceName ; switch ( resourceType ) { case ChangeStatusResourceType . AdGroup : resourceName = row . ChangeStatus . AdGroup ; break ; case ChangeStatusResourceType . AdGroupAd : resourceName = row . ChangeStatus . AdGroupAd ; break ; case ChangeStatusResourceType . AdGroupCriterion : resourceName = row . ChangeStatus . AdGroupCriterion ; break ; case ChangeStatusResourceType . Campaign : resourceName = row . ChangeStatus . Campaign ; break ; case ChangeStatusResourceType . CampaignCriterion : resourceName = row . ChangeStatus . CampaignCriterion ; break ; case ChangeStatusResourceType . Unknown : case ChangeStatusResourceType . Unspecified : default : resourceName = "" ; break ; } return resourceName ; }
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId) { $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); // Creates a query to find information about changed resources in your account. $query = 'SELECT change_status.resource_name, ' . 'change_status.last_change_date_time, ' . 'change_status.resource_status, ' . 'change_status.resource_type, ' . 'change_status.ad_group, ' . 'change_status.ad_group_ad, ' . 'change_status.ad_group_bid_modifier, ' . 'change_status.ad_group_criterion, ' . 'change_status.ad_group_feed, ' . 'change_status.campaign, ' . 'change_status.campaign_criterion, ' . 'change_status.campaign_feed, ' . 'change_status.feed, ' . 'change_status.feed_item ' . 'FROM change_status ' . 'WHERE change_status.last_change_date_time DURING LAST_14_DAYS ' . 'ORDER BY change_status.last_change_date_time ' . 'LIMIT 10000'; // Issues a search request. $response = $googleAdsServiceClient->search( SearchGoogleAdsRequest::build($customerId, $query) ); // Iterates over all rows in all pages and prints the requested field values for // the change status in each row. foreach ($response->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ printf( "On %s, change status '%s' shows resource '%s' with type '%s' and status '%s'.%s", $googleAdsRow->getChangeStatus()->getLastChangeDateTime(), $googleAdsRow->getChangeStatus()->getResourceName(), self::getResourceNameForResourceType($googleAdsRow->getChangeStatus()), ChangeStatusResourceType::name( $googleAdsRow->getChangeStatus()->getResourceType() ), ChangeStatusOperation::name($googleAdsRow->getChangeStatus()->getResourceStatus()), PHP_EOL ); } } /** * Gets the resource name for the resource type of the change status object. * * Each returned row contains all possible changed resources, only one of which is populated * with the name of the changed resource. This function returns the resource name of the * changed resource based on the resource type. * * @param ChangeStatus $changeStatus the change status object for getting changed resource * @return string the name of the resource that changed */ private static function getResourceNameForResourceType( ChangeStatus $changeStatus ) { $resourceType = $changeStatus->getResourceType(); $resourceName = ''; // Default value for UNSPECIFIED or UNKNOWN resource type. switch ($resourceType) { case ChangeStatusResourceType::AD_GROUP: $resourceName = $changeStatus->getAdGroup(); break; case ChangeStatusResourceType::AD_GROUP_AD: $resourceName = $changeStatus->getAdGroupAd(); break; case ChangeStatusResourceType::AD_GROUP_BID_MODIFIER: $resourceName = $changeStatus->getAdGroupBidModifier(); break; case ChangeStatusResourceType::AD_GROUP_CRITERION: $resourceName = $changeStatus->getAdGroupCriterion(); break; case ChangeStatusResourceType::AD_GROUP_FEED: $resourceName = $changeStatus->getAdGroupFeed(); break; case ChangeStatusResourceType::CAMPAIGN: $resourceName = $changeStatus->getCampaign(); break; case ChangeStatusResourceType::CAMPAIGN_CRITERION: $resourceName = $changeStatus->getCampaignCriterion(); break; case ChangeStatusResourceType::CAMPAIGN_FEED: $resourceName = $changeStatus->getCampaignFeed(); break; case ChangeStatusResourceType::FEED: $resourceName = $changeStatus->getFeed(); break; case ChangeStatusResourceType::FEED_ITEM: $resourceName = $changeStatus->getFeedItem(); break; } return $resourceName; }
