Lo stato delle modifiche consente di monitorare le risorse modificate in un account in un determinato periodo di tempo. Se una risorsa ha subito più modifiche durante un determinato periodo di tempo, viene restituita solo l'ultima modifica. Puoi quindi determinare se devi sincronizzare i valori del tuo database locale con quelli che sono stati modificati nel periodo di tempo.
Ad esempio, se durante un determinato periodo di tempo aggiungi e aggiorni una determinata campagna, viene restituito solo lo stato di modifica per UPDATE e non per l'operazione ADD. Se sposti la fine del periodo di tempo prima dell'aggiornamento, vedrai l'operazione ADD.
Se vuoi ottenere i risultati completi campo per campo con una visualizzazione dettagliata simile alla pagina web Cronologia delle modifiche, consulta Modifica evento.
Modifica tipi di stato
Vengono monitorati i seguenti tipi di risorse. Tieni presente che gli ID del tipo di risorsa sono diversi dagli indici dei valori di enumerazione di ChangeStatusResourceType.
| Tipo di risorsa | Valore | ID tipo di risorsa |
|---|---|---|
| Entità principali | ||
| Gruppo di annunci | AD_GROUP | 2 |
| Annuncio del gruppo di annunci | AD_GROUP_AD | 3 |
| Modificatore offerta per gruppo di annunci | AD_GROUP_BID_MODIFIER | 11 |
| Criterio del gruppo di annunci | AD_GROUP_CRITERION | 4 |
| Feed del gruppo di annunci | AD_GROUP_FEED | 12 |
| Priorità | CAMPAGNA | 5 |
| Criterio campagna | CAMPAIGN_CRITERION | 6 |
| Feed | ||
| Feed campagna | CAMPAIGN_FEED | 9 |
| Feed | FEED | 8 |
| Elemento del feed | FEED_ITEM | 10 |
| Insiemi condivisi | ||
| Set condiviso | SHARED_SET | 17 |
| Set condiviso della campagna | CAMPAIGN_SHARED_SET | 18 |
| Asset | ||
| Asset | RISORSA | 13 |
| Asset del cliente | CUSTOMER_ASSET | 14 |
| Asset della campagna | CAMPAIGN_ASSET | 15 |
| Asset del gruppo di annunci | AD_GROUP_ASSET | 16 |
Determinazione del tipo di risorsa in base all'ID
L'API Google Ads può restituire righe con un valore di tipo di risorsa UNKNOWN per le versioni precedenti, vale a dire che il tipo è supportato in una versione futura dell'API Google Ads, ma non era completamente supportato al momento del rilascio della versione corrente. In questo caso, puoi comunque determinare il tipo di risorsa della riga analizzando il valore resource_name restituito.
Il formato del nome della risorsa è:
customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}
Potrebbero essere presenti uno o più ID aggiuntivi, separati dal carattere -, ma quello pertinente è resource_type_id, il secondo ID dopo la barra finale. La tabella precedente elenca tutti gli ID dei tipi di risorsa.
Recupera le modifiche
L'elenco delle modifiche può essere filtrato per data e per tipo di risorsa. L'operazione su una determinata risorsa è di tipo ADDED, CHANGED o REMOVED.
Puoi recuperare l'elenco di tutte le modifiche per tutti i tipi di risorsa. Il campo resource_type restituito è il campo che è stato modificato. Vengono compilati anche tutti i campi principali. Ad esempio, se ad_group_criterion è cambiato, viene compilato anche il campo ad_group.
Potrebbero essere necessari fino a 3 minuti prima che la modifica venga riportata nei risultati della modifica dello stato.
La query deve filtrare in base a una data compresa negli ultimi 90 giorni e, facoltativamente, in un'ora e deve includere una clausola LIMIT impostata su un massimo di 10.000 risultati.
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.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";
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.V16.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 using pages of the specified
// page size.
SearchGoogleAdsRequest request = new SearchGoogleAdsRequest()
{
PageSize = PAGE_SIZE,
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 by specifying page size.
$response = $googleAdsServiceClient->search(
SearchGoogleAdsRequest::build($customerId, $query)->setPageSize(self::PAGE_SIZE)
);
// 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;
}
Python
def main(client, customer_id):
ads_service = client.get_service("GoogleAdsService")
# Construct 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_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"""
search_request = client.get_type("SearchGoogleAdsRequest")
search_request.customer_id = customer_id
search_request.query = query
search_request.page_size = _DEFAULT_PAGE_SIZE
response = ads_service.search(request=search_request)
for row in response:
cs = row.change_status
resource_type = cs.resource_type.name
if resource_type == "AD_GROUP":
resource_name = cs.ad_group
elif resource_type == "AD_GROUP_AD":
resource_name = cs.ad_group_ad
elif resource_type == "AD_GROUP_CRITERION":
resource_name = cs.ad_group_criterion
elif resource_type == "CAMPAIGN":
resource_name = cs.campaign
elif resource_type == "CAMPAIGN_CRITERION":
resource_name = cs.campaign_criterion
else:
resource_name = "UNKNOWN"
resource_status = cs.resource_status.name
print(
f"On '{cs.last_change_date_time}', change status "
f"'{cs.resource_name}' shows that a resource type of "
f"'{resource_type}' with resource name '{resource_name}' was "
f"{resource_status}"
)
Ruby
def get_change_summary(customer_id)
# GoogleAdsClient will read a config file from
# ENV['HOME']/google_ads_config.rb when called without parameters
client = Google::Ads::GoogleAds::GoogleAdsClient.new
# Construct a query to find information about changed resources in your
# account.
query = <<~QUERY
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
QUERY
# Execute the query.
response = client.service.google_ads.search(
customer_id: customer_id,
query: query,
page_size: PAGE_SIZE
)
# Process the results.
response.each do |row|
cs = row.change_status
resource_name = case cs.resource_type
when :AD_GROUP
cs.ad_group
when :AD_GROUP_AD
cs.ad_group_ad
when :AD_GROUP_CRITERION
cs.ad_group_criterion
when :CAMPAIGN
cs.campaign
when :CAMPAIGN_CRITERION
cs.campaign_criterion
else
"UNKNOWN"
end
puts "On #{cs.last_change_date_time}, change status #{cs.resource_name} " \
"shows a resource type of #{cs.resource_type} " \
"with resource name #{resource_name} was #{cs.resource_status}."
end
end
Perl
sub get_change_summary {
my ($api_client, $customer_id) = @_;
# Construct a search query to find information about changed resources in your
# account.
my $search_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";
# Create a search Google Ads request that will retrieve all change statuses using
# pages of the specified page size.
my $search_request =
Google::Ads::GoogleAds::V16::Services::GoogleAdsService::SearchGoogleAdsRequest
->new({
customerId => $customer_id,
query => $search_query,
pageSize => PAGE_SIZE
});
# Get the GoogleAdsService.
my $google_ads_service = $api_client->GoogleAdsService();
my $iterator = Google::Ads::GoogleAds::Utils::SearchGoogleAdsIterator->new({
service => $google_ads_service,
request => $search_request
});
# Iterate over all rows in all pages and print the requested field values for
# the change status in each row.
while ($iterator->has_next) {
my $google_ads_row = $iterator->next;
my $change_status = $google_ads_row->{changeStatus};
printf "On %s, change status '%s' shows a resource type of '%s' " .
"with resource name '%s' was '%s'.\n",
$change_status->{lastChangeDateTime},
$change_status->{resourceName}, $change_status->{resourceType},
__get_resource_name_for_resource_type($change_status),
$change_status->{resourceStatus};
}
return 1;
}
# This method 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.
sub __get_resource_name_for_resource_type {
my $change_status = shift;
my $resource_type = $change_status->{resourceType};
if ($resource_type eq AD_GROUP) {
return $change_status->{adGroup};
} elsif ($resource_type eq AD_GROUP_AD) {
return $change_status->{adGroupAd};
} elsif ($resource_type eq AD_GROUP_BID_MODIFIER) {
return $change_status->{adGroupBidModifier};
} elsif ($resource_type eq AD_GROUP_CRITERION) {
return $change_status->{adGroupCriterion};
} elsif ($resource_type eq AD_GROUP_FEED) {
return $change_status->{adGroupFeed};
} elsif ($resource_type eq CAMPAIGN) {
return $change_status->{campaign};
} elsif ($resource_type eq CAMPAIGN_CRITERION) {
return $change_status->{campaignCriterion};
} elsif ($resource_type eq CAMPAIGN_FEED) {
return $change_status->{campaignFeed};
} elsif ($resource_type eq FEED) {
return $change_status->{feed};
} elsif ($resource_type eq FEED_ITEM) {
return $change_status->{feedItem};
} else {
return "";
}
}
Sincronizza localmente
Dopo aver recuperato l'esatto resource_name, è necessario creare una nuova query con questo nome risorsa per ottenere tutti i valori correnti della risorsa. Lo stato della modifica non viene monitorato per i valori modificati di una specifica risorsa, ma solo per quali risorse sono state modificate. La determinazione
della differenza tra i valori precedenti e attuali è responsabilità del
programma di chiamata.
Data/ora modifica
Il campo last_change_date_time indica quando è avvenuta la modifica più recente a una risorsa. Pertanto, l'aggiornamento dei dati memorizzati nella cache locale può essere confrontato con il valore di questo campo per determinare se i dati locali sono obsoleti.
Tieni presente che questo campo è anche filtrabile, ovvero può essere utilizzato nella clausola WHERE
di una query GAQL (Google Ads Query Language), in modo da eseguire query per
le modifiche alle risorse che si sono verificate prima o dopo un determinato periodo di tempo.
Ad esempio, per trovare tutte le modifiche che si sono verificate per un determinato tipo di risorsa nell'ultima settimana, puoi utilizzare la seguente clausola relativa al predicato GAQL:
WHERE change_status.last_change_date_time DURING LAST_7_DAYS