Zmień stan

ChangeStatus umożliwia śledzenie zasobów, które uległy zmianie na koncie w danym okresie. Jeśli w danym okresie wprowadzono wiele zmian w zasobie, zwracana jest tylko ostatnia zmiana. Następnie możesz określić, czy musisz zsynchronizować wartości w lokalnej bazie danych z tymi, które zmieniły się w danym okresie.

Jeśli na przykład w danym okresie dodasz, a potem zaktualizujesz kampanię, zwrócony zostanie tylko stan zmiany dla operacji UPDATE, a nie dla operacji ADD. Jeśli przesuniesz koniec przedziału czasowego przed aktualizację, zobaczysz operację ADD.

Jeśli chcesz zobaczyć pełne wyniki dla poszczególnych pól w widoku szczegółowym, zapoznaj się z artykułem ChangeEvent.

Ważne: nie wszystkie wiersze ze stanu zmiany mają odpowiadające im szczegóły w zdarzeniu zmiany. Zobacz ograniczenia zdarzeń zmiany.

Ważne: niektóre wiersze ze stanu zmiany mogą nie być widoczne w historii zmian w interfejsie internetowym Google Ads. Interfejs internetowy ma dodatkową logikę biznesową i reguły renderowania, które zmieniają jego dane wyjściowe w porównaniu ze stanem zmiany.

Zakres raportowanych zmian

Gdy ChangeStatus wskazuje zmianę zasobu, np. CAMPAIGN, oznacza to, że zmodyfikowano sam zasób lub jeden z jego zasobów podrzędnych, np. grupę reklam, reklamę lub kryterium w kampanii.

Zasób ChangeStatus ma na celu zapewnienie ogólnego przeglądu aktywności w poszczególnych częściach konta. Jeśli nastąpi zmiana w zasobie podrzędnym, może zostać zwrócony identyfikator zasobu nadrzędnego, aby nie pominąć żadnych zmian. Dotyczy to zwłaszcza typów zasobów, które nie są wyraźnie wymienione w typie wyliczeniowym ChangeStatusResourceType.

Na przykład zmiana modyfikatora stawek grupy reklam powoduje zwrócenie typu zasobu AdGroupBidModifier, ale zmiana mniej szczegółowego lub nowszego elementu podrzędnego może spowodować zwrócenie elementu nadrzędnego Campaign lub AdGroup.

Aby uzyskać szczegółowe informacje o tym, co dokładnie się zmieniło, możesz użyć zasobu ChangeEvent, który zawiera bardziej szczegółowy widok utworzonych i zaktualizowanych elementów.

Zmiana typów stanów

Śledzone są te typy zasobów: Pamiętaj, że identyfikatory typów zasobów różnią się od indeksów wartości wyliczeniowych ChangeStatusResourceType.

Typ zasobu	Wartość	Identyfikator typu zasobu
Podstawowe encje
Grupa reklam	AD_GROUP	2
Reklama z grupy reklam	AD_GROUP_AD	3
Modyfikator stawki grupy reklam	AD_GROUP_BID_MODIFIER	11
Kryterium w grupie reklam	AD_GROUP_CRITERION	4
Kanał grupy reklam	AD_GROUP_FEED	12
Grupa plików	ASSET_BUNDLE	19
Kampania	KAMPANIA	5
Budżet kampanii	CAMPAIGN_BUDGET	7
Kryterium kampanii	CAMPAIGN_CRITERION	6
Kanały
Kanał kampanii	CAMPAIGN_FEED	9
Karty	AKTYWNOŚĆ	8
Element kanału	FEED_ITEM	10
Zasoby wspólne
Wspólny zestaw	SHARED_SET	17
Wspólny zestaw kampanii	CAMPAIGN_SHARED_SET	18
Assets
Komponent	ZASÓB	13
Zestaw komponentów	ASSET_SET	25
Zasób klienta	CUSTOMER_ASSET	14
Komponent kampanii	CAMPAIGN_ASSET	15
Zestaw komponentów kampanii	CAMPAIGN_ASSET_SET	26
Komponent grupy reklam	AD_GROUP_ASSET	16

Określanie typu zasobu według identyfikatora

Interfejs Google Ads API może zwracać wiersze z wartością typu zasobu UNKNOWN w przypadku wcześniejszych wersji interfejsu API, co oznacza, że dany typ jest obsługiwany w późniejszej wersji interfejsu Google Ads API, ale nie był w pełni obsługiwany w momencie wydania wcześniejszej wersji. W takim przypadku możesz określić typ zasobu wiersza, analizując zwrócony obiekt resource_name.

Format nazwy zasobu:

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

Może być więcej identyfikatorów, rozdzielonych znakiem -, ale ten, który nas interesuje, to resource_type_id – drugi identyfikator po ostatnim ukośniku. W poprzedniej tabeli znajdziesz listę wszystkich identyfikatorów typów zasobów.

Pobieranie zmian

Listę zmian można filtrować według daty i typu zasobu. Operacja na danym zasobie to ADDED, CHANGED lub REMOVED.

Możesz pobrać listę wszystkich zmian we wszystkich typach zasobów. Zwrócony obiekt resource_type to pole, które uległo zmianie. Wypełniane są też wszystkie pola nadrzędne. Jeśli na przykład zmieniła się wartość ad_group_criterion, pole ad_group również zostanie wypełnione.

Zanim zmiana zostanie odzwierciedlona w wynikach stanu zmiany, może minąć do 3 minut.

Zapytanie musi filtrować według daty z ostatnich 90 dni i opcjonalnie według godziny oraz musi zawierać klauzulę LIMIT ustawioną na maksymalnie 10 000 wyników.

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

Uwaga: nie podajemy tutaj bezpośredniego przykładowego kodu REST dla tego kroku, ale możesz to zrobić za pomocą ręcznego żądania REST.

Zapoznaj się z dokumentacją interfejsu REST interfejsu Google Ads API i stronami referencyjnymi dotyczącymi poszczególnych metod. Musisz utworzyć ładunek JSON na podstawie definicji proto.

Najważniejsze materiały:

• Korzystanie z REST
• Struktura interfejsu REST
• Mapowanie pól JSON
• Zapoznaj się z dokumentacją interfejsu API typu REST dotyczącą konkretnej usługi i metody.

Synchronizuj lokalnie

Po pobraniu dokładnej wartości resource_name należy utworzyć nowe zapytanie z tą nazwą zasobu, aby uzyskać wszystkie bieżące wartości zasobu. Stan zmiany nie jest śledzony w przypadku zmienionych wartości konkretnego zasobu – śledzone są tylko informacje o tym, które zasoby uległy zmianie. Określenie różnicy między poprzednimi a bieżącymi wartościami należy do programu wywołującego.

Zmień godzinę

Pole last_change_date_time wskazuje, kiedy nastąpiła ostatnia zmiana zasobu. Dzięki temu można porównać aktualność danych produktów dostępnych lokalnie przechowywanych w pamięci podręcznej z wartością tego pola, aby określić, czy dane produktów dostępnych lokalnie są nieaktualne.

Pamiętaj, że to pole można też filtrować, co oznacza, że można go używać w klauzuli WHERE zapytania w języku zapytań Google Ads (GAQL), aby wyszukiwać zmiany w zasobach, które wystąpiły przed danym momentem lub po nim.

Na przykład znalezienie wszystkich zmian, które wystąpiły w przypadku określonego typu zasobu w ciągu ostatniego tygodnia, można wykonać za pomocą tej klauzuli predykatu GAQL:

WHERE change_status.last_change_date_time DURING LAST_7_DAYS