「變更事件」會詳細列出帳戶的變更內容。回報建立作業時，系統會傳回所有新的欄位值；回報更新作業時，系統會傳回新舊值，讓您全面掌握個別變更。
此外，系統也會指出用於進行變更的用戶端類型 (例如 API 或網頁用戶端)，以及進行變更的使用者 (假設該資訊也會顯示在網頁用戶端的變更記錄中)。
變更活動類型
請參閱ChangeEventResourceType的資源類型清單。
查詢
變更清單必須按日期篩選。日期範圍必須在過去 30 天內。
查詢也必須包含 LIMIT 子句，將結果限制在最多 10,000 列。如果需要超過 10,000 筆結果，請記下傳回結果集中最後一筆記錄的時間戳記，然後在後續查詢中設定日期範圍，從該時間之後開始，繼續上次的查詢。
變更最多可能需要三分鐘才會反映在變更事件結果中。
以下範例說明如何擷取及處理變更事件，包括判斷變更者、變更者使用的用戶端類型，以及變更中每個欄位的舊值和新值：
Java
private void runExample(GoogleAdsClient googleAdsClient, long customerId) { // Defines a GAQL query to retrieve change_event instances from the last 14 days. String query = String.format( "SELECT" + " change_event.resource_name," + " change_event.change_date_time," + " change_event.change_resource_name," + " change_event.user_email," + " change_event.client_type," + " change_event.change_resource_type," + " change_event.old_resource," + " change_event.new_resource," + " change_event.resource_change_operation," + " change_event.changed_fields " + "FROM " + " change_event " + "WHERE " + " change_event.change_date_time <= '%s' " + " AND change_event.change_date_time >= '%s' " + "ORDER BY" + " change_event.change_date_time DESC " + "LIMIT 5", LocalDate.now().toString("YYYY-MM-dd"), LocalDate.now().minusDays(14).toString("YYYY-MM-dd")); // Creates a GoogleAdsServiceClient instance. try (GoogleAdsServiceClient client = googleAdsClient.getLatestVersion().createGoogleAdsServiceClient()) { // Issues the search query. SearchPagedResponse response = client.search(String.valueOf(customerId), query); // Processes the rows of the response. for (GoogleAdsRow row : response.iterateAll()) { ChangeEvent event = row.getChangeEvent(); // Prints some general information about the change event. System.out.printf( "On '%s', user '%s' used interface '%s' to perform a(n) '%s' operation on a '%s' with" + " resource name '%s'.%n", event.getChangeDateTime(), event.getUserEmail(), event.getClientType(), event.getResourceChangeOperation(), event.getChangeResourceType(), event.getResourceName()); // Prints some detailed information about update and create operations. if (event.getResourceChangeOperation() == ResourceChangeOperation.UPDATE || event.getResourceChangeOperation() == ResourceChangeOperation.CREATE) { // Retrieves the entity that was changed. Optional<Message> oldResource = getResourceByType(event.getOldResource(), event.getChangeResourceType()); Optional<Message> newResource = getResourceByType(event.getNewResource(), event.getChangeResourceType()); // Prints the old and new values for each field that was updated/created. for (String changedPath : row.getChangeEvent().getChangedFields().getPathsList()) { // Uses the FieldMasks utility to retrieve a value from a . delimited path. List<? extends Object> oldValue = oldResource.isPresent() ? FieldMasks.getFieldValue(changedPath, oldResource.get()) : Collections.emptyList(); List<? extends Object> newValue = newResource.isPresent() ? FieldMasks.getFieldValue(changedPath, newResource.get()) : Collections.emptyList(); // Prints different messages for UPDATE and CREATE cases. if (event.getResourceChangeOperation() == ResourceChangeOperation.UPDATE) { System.out.printf("\t %s changed from %s to %s.%n", changedPath, oldValue, newValue); } else if (event.getResourceChangeOperation() == ResourceChangeOperation.CREATE) { System.out.printf("\t %s set to %s.%n", changedPath, newValue); } } } } } }
C#
public void Run(GoogleAdsClient client, long customerId) { // Get the GoogleAdsService. GoogleAdsServiceClient googleAdsService = client.GetService( Services.V22.GoogleAdsService); // Construct a query to find details for recent changes in your account. // The LIMIT clause is required for the change_event resource. // The maximum size is 10000, but a low limit was set here for demonstrative // purposes. // The WHERE clause on change_date_time is also required. It must specify a // window of at most 30 days within the past 30 days. string startDate = DateTime.Today.Subtract(TimeSpan.FromDays(25)).ToString("yyyyMMdd"); string endDate = DateTime.Today.Add(TimeSpan.FromDays(1)).ToString("yyyyMMdd"); string searchQuery = $@" SELECT change_event.resource_name, change_event.change_date_time, change_event.change_resource_name, change_event.user_email, change_event.client_type, change_event.change_resource_type, change_event.old_resource, change_event.new_resource, change_event.resource_change_operation, change_event.changed_fields FROM change_event WHERE change_event.change_date_time >= '{startDate}' AND change_event.change_date_time <= '{endDate}' ORDER BY change_event.change_date_time DESC LIMIT 5"; try { // Issue a search request. googleAdsService.SearchStream(customerId.ToString(), searchQuery, delegate (SearchGoogleAdsStreamResponse resp) { // Display the results. foreach (GoogleAdsRow googleAdsRow in resp.Results) { ChangeEvent changeEvent = googleAdsRow.ChangeEvent; ChangedResource oldResource = changeEvent.OldResource; ChangedResource newResource = changeEvent.NewResource; bool knownResourceType = true; IMessage oldResourceEntity = null; IMessage newResourceEntity = null; switch (changeEvent.ChangeResourceType) { case ChangeEventResourceType.Ad: oldResourceEntity = oldResource.Ad; newResourceEntity = newResource.Ad; break; case ChangeEventResourceType.AdGroup: oldResourceEntity = oldResource.AdGroup; newResourceEntity = newResource.AdGroup; break; case ChangeEventResourceType.AdGroupAd: oldResourceEntity = oldResource.AdGroupAd; newResourceEntity = newResource.AdGroupAd; break; case ChangeEventResourceType.AdGroupAsset: oldResourceEntity = oldResource.AdGroupAsset; newResourceEntity = newResource.AdGroupAsset; break; case ChangeEventResourceType.AdGroupBidModifier: oldResourceEntity = oldResource.AdGroupBidModifier; newResourceEntity = newResource.AdGroupBidModifier; break; case ChangeEventResourceType.AdGroupCriterion: oldResourceEntity = oldResource.AdGroupCriterion; newResourceEntity = newResource.AdGroupCriterion; break; case ChangeEventResourceType.Asset: oldResourceEntity = oldResource.Asset; newResourceEntity = newResource.Asset; break; case ChangeEventResourceType.AssetSet: oldResourceEntity = oldResource.AssetSet; newResourceEntity = newResource.AssetSet; break; case ChangeEventResourceType.AssetSetAsset: oldResourceEntity = oldResource.AssetSetAsset; newResourceEntity = newResource.AssetSetAsset; break; case ChangeEventResourceType.Campaign: oldResourceEntity = oldResource.Campaign; newResourceEntity = newResource.Campaign; break; case ChangeEventResourceType.CampaignAsset: oldResourceEntity = oldResource.CampaignAsset; newResourceEntity = newResource.CampaignAsset; break; case ChangeEventResourceType.CampaignAssetSet: oldResourceEntity = oldResource.CampaignAssetSet; newResourceEntity = newResource.CampaignAssetSet; break; case ChangeEventResourceType.CampaignBudget: oldResourceEntity = oldResource.CampaignBudget; newResourceEntity = newResource.CampaignBudget; break; case ChangeEventResourceType.CampaignCriterion: oldResourceEntity = oldResource.CampaignCriterion; newResourceEntity = newResource.CampaignCriterion; break; case ChangeEventResourceType.CustomerAsset: oldResourceEntity = oldResource.CustomerAsset; newResourceEntity = newResource.CustomerAsset; break; default: knownResourceType = false; break; } if (!knownResourceType) { Console.WriteLine($"Unknown change_resource_type " + $"'{changeEvent.ChangeResourceType}'."); continue; } Console.WriteLine($"On #{changeEvent.ChangeDateTime}, user " + $"{changeEvent.UserEmail} used interface {changeEvent.ClientType} " + $"to perform a(n) '{changeEvent.ResourceChangeOperation}' " + $"operation on a '{changeEvent.ChangeResourceType}' with " + $"resource name {changeEvent.ChangeResourceName}."); foreach (string fieldMaskPath in changeEvent.ChangedFields.Paths) { if (changeEvent.ResourceChangeOperation == ResourceChangeOperation.Create) { object newValue = FieldMasks.GetFieldValue( fieldMaskPath, newResourceEntity); Console.WriteLine($"\t{fieldMaskPath} set to '{newValue}'."); } else if (changeEvent.ResourceChangeOperation == ResourceChangeOperation.Update) { object oldValue = FieldMasks.GetFieldValue(fieldMaskPath, oldResourceEntity); object newValue = FieldMasks.GetFieldValue(fieldMaskPath, newResourceEntity); Console.WriteLine($"\t{fieldMaskPath} changed from " + $"'{oldValue}' to '{newValue}'."); } } } }); } catch (GoogleAdsException e) { Console.WriteLine("Failure:"); Console.WriteLine($"Message: {e.Message}"); Console.WriteLine($"Failure: {e.Failure}"); Console.WriteLine($"Request ID: {e.RequestId}"); throw; } }
PHP
public static function runExample(GoogleAdsClient $googleAdsClient, int $customerId) { $googleAdsServiceClient = $googleAdsClient->getGoogleAdsServiceClient(); // Constructs a query to find details for recent changes in your account. // The LIMIT clause is required for the change_event resource. // The maximum size is 10000, but a low limit was set here for demonstrative // purposes. // The WHERE clause on change_date_time is also required. It must specify a // window of at most 30 days within the past 30 days. $query = 'SELECT change_event.resource_name, ' . 'change_event.change_date_time, ' . 'change_event.change_resource_name, ' . 'change_event.user_email, ' . 'change_event.client_type, ' . 'change_event.change_resource_type, ' . 'change_event.old_resource, ' . 'change_event.new_resource, ' . 'change_event.resource_change_operation, ' . 'change_event.changed_fields ' . 'FROM change_event ' . sprintf( 'WHERE change_event.change_date_time <= %s ', date_format(new DateTime('+1 day'), 'Ymd') ) . sprintf( 'AND change_event.change_date_time >= %s ', date_format(new DateTime('-14 days'), 'Ymd') ) . 'ORDER BY change_event.change_date_time DESC ' . 'LIMIT 5'; // 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 event in each row. foreach ($response->iterateAllElements() as $googleAdsRow) { /** @var GoogleAdsRow $googleAdsRow */ $changeEvent = $googleAdsRow->getChangeEvent(); $oldResource = $changeEvent->getOldResource(); $newResource = $changeEvent->getNewResource(); $isResourceTypeKnown = true; $oldResourceEntity = null; $newResourceEntity = null; switch ($changeEvent->getChangeResourceType()) { case ChangeEventResourceType::AD: $oldResourceEntity = $oldResource->getAd(); $newResourceEntity = $newResource->getAd(); break; case ChangeEventResourceType::AD_GROUP: $oldResourceEntity = $oldResource->getAdGroup(); $newResourceEntity = $newResource->getAdGroup(); break; case ChangeEventResourceType::AD_GROUP_AD: $oldResourceEntity = $oldResource->getAdGroupAd(); $newResourceEntity = $newResource->getAdGroupAd(); break; case ChangeEventResourceType::AD_GROUP_ASSET: $oldResourceEntity = $oldResource->getAdGroupAsset(); $newResourceEntity = $newResource->getAdGroupAsset(); break; case ChangeEventResourceType::AD_GROUP_CRITERION: $oldResourceEntity = $oldResource->getAdGroupCriterion(); $newResourceEntity = $newResource->getAdGroupCriterion(); break; case ChangeEventResourceType::AD_GROUP_BID_MODIFIER: $oldResourceEntity = $oldResource->getAdGroupBidModifier(); $newResourceEntity = $newResource->getAdGroupBidModifier(); break; case ChangeEventResourceType::ASSET: $oldResourceEntity = $oldResource->getAsset(); $newResourceEntity = $newResource->getAsset(); break; case ChangeEventResourceType::ASSET_SET: $oldResourceEntity = $oldResource->getAssetSet(); $newResourceEntity = $newResource->getAssetSet(); break; case ChangeEventResourceType::ASSET_SET_ASSET: $oldResourceEntity = $oldResource->getAssetSetAsset(); $newResourceEntity = $newResource->getAssetSetAsset(); break; case ChangeEventResourceType::CAMPAIGN: $oldResourceEntity = $oldResource->getCampaign(); $newResourceEntity = $newResource->getCampaign(); break; case ChangeEventResourceType::CAMPAIGN_ASSET: $oldResourceEntity = $oldResource->getCampaignAsset(); $newResourceEntity = $newResource->getCampaignAsset(); break; case ChangeEventResourceType::CAMPAIGN_ASSET_SET: $oldResourceEntity = $oldResource->getCampaignAssetSet(); $newResourceEntity = $newResource->getCampaignAssetSet(); break; case ChangeEventResourceType::CAMPAIGN_BUDGET: $oldResourceEntity = $oldResource->getCampaignBudget(); $newResourceEntity = $newResource->getCampaignBudget(); break; case ChangeEventResourceType::CAMPAIGN_CRITERION: $oldResourceEntity = $oldResource->getCampaignCriterion(); $newResourceEntity = $newResource->getCampaignCriterion(); break; case ChangeEventResourceType::CUSTOMER_ASSET: $oldResourceEntity = $oldResource->getCustomerAsset(); $newResourceEntity = $newResource->getCustomerAsset(); break; default: $isResourceTypeKnown = false; break; } if (!$isResourceTypeKnown) { printf( "Unknown change_resource_type %s.%s", ChangeEventResourceType::name($changeEvent->getChangeResourceType()), PHP_EOL ); } $resourceChangeOperation = $changeEvent->getResourceChangeOperation(); printf( "On %s, user '%s' used interface '%s' to perform a(n) '%s' operation on a '%s' " . "with resource name '%s'.%s", $changeEvent->getChangeDateTime(), $changeEvent->getUserEmail(), ChangeClientType::name($changeEvent->getClientType()), ResourceChangeOperation::name($resourceChangeOperation), ChangeEventResourceType::name($changeEvent->getChangeResourceType()), $changeEvent->getChangeResourceName(), PHP_EOL ); if ( $resourceChangeOperation !== ResourceChangeOperation::CREATE && $resourceChangeOperation !== ResourceChangeOperation::UPDATE ) { continue; } foreach ($changeEvent->getChangedFields()->getPaths() as $path) { $newValueStr = self::convertToString( FieldMasks::getFieldValue($path, $newResourceEntity, true) ); if ($resourceChangeOperation === ResourceChangeOperation::CREATE) { printf("\t'$path' set to '%s'.%s", $newValueStr, PHP_EOL); } elseif ($resourceChangeOperation === ResourceChangeOperation::UPDATE) { printf( "\t'$path' changed from '%s' to '%s'.%s", self::convertToString( FieldMasks::getFieldValue($path, $oldResourceEntity, true) ), $newValueStr, PHP_EOL ); } } } } /** * Converts the specified value to string. * * @param mixed $value the value to be converted to string * @return string the value in string */ private static function convertToString($value) { if (is_null($value)) { return 'no value'; } if (gettype($value) === 'boolean') { return $value ? 'true' : 'false'; } elseif (gettype($value) === 'object') { if (get_class($value) === RepeatedField::class) { $strValues = []; foreach (iterator_to_array($value->getIterator()) as $element) { /** @type Message $element */ $strValues[] = $element->serializeToJsonString(); } return '[' . implode(',', $strValues) . ']'; } return json_encode($value); } else { return strval($value); } }