Status ändern

ChangeStatus bietet eine Möglichkeit, nachzuverfolgen, welche Ressourcen sich innerhalb eines Kontos in einem bestimmten Zeitraum geändert haben. Wenn eine Ressource im angegebenen Zeitraum mehrmals geändert wurde, wird nur die letzte Änderung zurückgegeben. Anschließend können Sie festlegen, ob Sie die Werte Ihrer lokalen Datenbank mit den Werten synchronisieren müssen, die sich im entsprechenden Zeitraum geändert haben.

Wenn Sie beispielsweise in einem bestimmten Zeitraum eine Kampagne hinzufügen und dann aktualisieren, wird nur der Änderungsstatus für den Vorgang UPDATE und nicht für den Vorgang ADD zurückgegeben. Wenn Sie das Ende des Zeitraums auf einen Zeitpunkt vor der Aktualisierung verschieben, wird der Vorgang ADD angezeigt.

Wenn Sie die vollständigen Ergebnisse Feld für Feld mit einer detaillierten Ansicht sehen möchten, lesen Sie ChangeEvent.

Wichtig: Nicht alle Zeilen aus dem Änderungsstatus haben entsprechende Details im Änderungsereignis. Weitere Informationen finden Sie unter Einschränkungen für Änderungsereignisse.

Wichtig: Einige Zeilen aus dem Änderungsstatus werden möglicherweise nicht im Änderungsverlauf der Google Ads-Weboberfläche angezeigt. Die Weboberfläche hat zusätzliche Geschäftslogik und Rendering-Regeln, die die Ausgabe im Vergleich zum Änderungsstatus verändern.

Umfang der gemeldeten Änderungen

Wenn ChangeStatus eine Änderung an einer Ressource angibt, z. B. an einer CAMPAIGN, bedeutet das, dass entweder die Ressource selbst oder eine ihrer untergeordneten Ressourcen (eine Anzeigengruppe, eine Anzeige oder ein Kriterium innerhalb dieser Kampagne) geändert wurde.

Die Ressource ChangeStatus soll einen allgemeinen Überblick darüber geben, in welchen Bereichen Ihres Kontos Aktivitäten stattgefunden haben. Wenn eine Änderung in einer untergeordneten Ressource auftritt, wird möglicherweise die ID der übergeordneten Ressource zurückgegeben, damit keine Änderungen übersehen werden. Dies gilt insbesondere für Ressourcentypen, die nicht explizit im Enum ChangeStatusResourceType aufgeführt sind.

Beispielsweise wird bei einer Änderung an einer Gebotsanpassung für eine Anzeigengruppe der Ressourcentyp AdGroupBidModifier gemeldet. Bei einer Änderung an einer weniger detaillierten oder neueren untergeordneten Entität wird stattdessen möglicherweise die übergeordnete Entität Campaign oder AdGroup gemeldet.

Wenn Sie Details auf Feldebene zu den genauen Änderungen erhalten möchten, können Sie die Ressource ChangeEvent verwenden, die eine detailliertere Ansicht der Erstellungen und Aktualisierungen bietet.

Änderungsstatustypen

Die folgenden Ressourcentypen werden erfasst. Beachten Sie, dass sich die Ressourcentyp-IDs von den Enum-Wertindexen von ChangeStatusResourceType unterscheiden.

Ressourcentyp	Wert	Ressourcentyp-ID
Hauptentitäten
Anzeigengruppe	AD_GROUP	2
Anzeige in Anzeigengruppe	AD_GROUP_AD	3
Anpassung für Anzeigengruppengebot	AD_GROUP_BID_MODIFIER	11
Kriterium für Anzeigengruppe	AD_GROUP_CRITERION	4
Anzeigengruppen-Feed	AD_GROUP_FEED	12
Asset-Gruppe	ASSET_BUNDLE	19
Kampagne	KAMPAGNE	5
Kampagnenbudget	CAMPAIGN_BUDGET	7
Kampagnenkriterium	CAMPAIGN_CRITERION	6
Feeds
Kampagnen-Feed	CAMPAIGN_FEED	9
Feed	FEED	8
Feedelement	FEED_ITEM	10
Gemeinsame Sätze
Freigegebener Satz	SHARED_SET	17
Freigegebener Kampagnensatz	CAMPAIGN_SHARED_SET	18
Assets
Asset	ASSET	13
Asset-Sammlung	ASSET_SET	25
Asset des Kunden	CUSTOMER_ASSET	14
Asset der Kampagne	CAMPAIGN_ASSET	15
Asset-Sammlung der Kampagne	CAMPAIGN_ASSET_SET	26
Asset der Anzeigengruppe	AD_GROUP_ASSET	16

Ressourcentyp anhand der ID bestimmen

Die Google Ads API kann Zeilen mit dem Ressourcentypwert UNKNOWN für frühere API-Versionen zurückgeben. Das bedeutet, dass der Typ in einer späteren Version der Google Ads API unterstützt wird, aber bei der Veröffentlichung der früheren Version nicht vollständig unterstützt wurde. In diesem Fall können Sie den Ressourcentyp der Zeile trotzdem ermitteln, indem Sie den zurückgegebenen resource_name parsen.

Das Format des Ressourcennamens ist:

customers/{customer_id}/changeStatus/{timestamp}-{resource_type_id}-{additional_ids}

Es können eine oder mehrere zusätzliche IDs vorhanden sein, die durch das Zeichen - getrennt sind. Relevant ist jedoch die resource_type_id, die zweite ID nach dem letzten Schrägstrich. In der vorherigen Tabelle sind alle Ressourcentyp-IDs aufgeführt.

Änderungen abrufen

Die Liste der Änderungen kann nach Datum und Ressourcentyp gefiltert werden. Der Vorgang für eine bestimmte Ressource ist entweder ADDED, CHANGED oder REMOVED.

Sie können die Liste aller Änderungen für alle Ressourcentypen abrufen. Das zurückgegebene resource_type ist das Feld, das geändert wurde. Alle übergeordneten Felder werden ebenfalls ausgefüllt. Wenn sich beispielsweise ad_group_criterion geändert hat, wird auch das Feld ad_group ausgefüllt.

Es kann bis zu 3 Minuten dauern, bis eine Änderung in den Ergebnissen des Änderungsstatus angezeigt wird.

Die Abfrage muss nach einem Datum innerhalb der letzten 90 Tage und optional nach einer Uhrzeit filtern und eine LIMIT-Klausel enthalten, die auf maximal 10.000 Ergebnisse festgelegt ist.

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());
    }
  }
}
GetChangeSummary.java
      

C#

public void Run(GoogleAdsClient client, long customerId)
{
    // Get the GoogleAdsService.
    GoogleAdsServiceClient googleAdsService = client.GetService(
        Services.V26.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;
}
GetChangeSummary.cs
      

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;
}
GetChangeSummary.php
      

Python

def main(client: GoogleAdsClient, customer_id: str) -> None:
    ads_service: GoogleAdsServiceClient = 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: SearchGoogleAdsRequest = client.get_type(
        "SearchGoogleAdsRequest"
    )
    search_request.customer_id = customer_id
    search_request.query = query

    response: SearchPagedResponse = ads_service.search(request=search_request)

    row: GoogleAdsRow
    for row in response:
        cs: ChangeStatus = row.change_status
        resource_type: str = cs.resource_type.name
        resource_name: str
        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: str = 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}"
        )
get_change_summary.py
      

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,
  )

  # 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
get_change_summary.rb
      

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::V26::Services::GoogleAdsService::SearchGoogleAdsRequest
    ->new({
      customerId => $customer_id,
      query      => $search_query
    });

  # 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 "";
  }
}
get_change_summary.pl
      

curl

Hinweis: Für diesen Schritt wird hier kein direktes REST-Codebeispiel bereitgestellt. Sie können dies jedoch mit einer manuellen REST-Anfrage erreichen.

Weitere Informationen finden Sie in der Dokumentation zur REST-Schnittstelle der Google Ads API und auf den methodenspezifischen Referenzseiten. Sie müssen die JSON-Nutzlast anhand der Proto-Definitionen erstellen.

Wichtige Ressourcen:

• REST verwenden
• Struktur der REST-Schnittstelle
• JSON-Feldzuordnungen
• Informationen zum jeweiligen Dienst und zur Methode finden Sie in der REST API-Referenz.

Lokal synchronisieren

Sobald die genaue resource_name abgerufen wurde, sollte eine neue Abfrage mit diesem Ressourcennamen durchgeführt werden, um alle aktuellen Werte der Ressource zu erhalten. Der Änderungsstatus wird nicht für die geänderten Werte einer bestimmten Ressource erfasst, sondern nur dafür, welche Ressourcen sich geändert haben. Die Ermittlung der Differenz zwischen den vorherigen und den aktuellen Werten liegt in der Verantwortung des aufrufenden Programms.

Zeit ändern

Das Feld last_change_date_time gibt an, wann die letzte Änderung an einer Ressource vorgenommen wurde. So kann die Aktualität lokal im Cache gespeicherter Daten mit dem Wert dieses Felds verglichen werden, um festzustellen, ob lokale Daten veraltet sind.

Dieses Feld ist auch filterbar. Es kann also in der WHERE-Klausel einer GAQL-Abfrage (Google Ads Query Language) verwendet werden, um nach Änderungen an Ressourcen zu suchen, die vor oder nach einem bestimmten Zeitpunkt aufgetreten sind.

Wenn Sie beispielsweise alle Änderungen für einen bestimmten Ressourcentyp innerhalb der letzten Woche finden möchten, können Sie die folgende GAQL-Prädikatsklausel verwenden:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS