Zmień stan

Film: stan

ChangeStatus umożliwia śledzenie, które zasoby uległy zmianie na koncie w określonym przedziale czasu. Jeśli w danym okresie zasób został zmieniony kilka razy, zwracana jest tylko ostatnia zmiana. Następnie możesz określić, czy musisz zsynchronizować wartości w lokalnej bazie danych z wartościami, które uległy zmianie w danym okresie.

Jeśli na przykład w danym okresie dodasz, a potem zaktualizujesz daną kampanię, zwracany jest tylko stan zmiany operacji UPDATE, a nie operacji ADD. Jeśli przesuniesz koniec okresu przed aktualizację, zobaczysz operację ADD.

Jeśli chcesz zobaczyć pełne wyniki w podziale na poszczególne pola, kliknij ChangeEvent.

Określanie zakresu zgłaszanych zmian

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

ChangeStatus Ten zasób ma na celu przedstawienie ogólnego przeglądu części konta, na których odnotowano aktywność. Jeśli w zasobie podrzędnym nastąpi zmiana, może zostać zwrócony identyfikator zasobu nadrzędnego, aby mieć pewność, że żadne modyfikacje nie zostaną pominięte. Dotyczy to zwłaszcza typów zasobów, które nie są wyraźnie wymienione w wyliczeniu ChangeStatusResourceType.

Na przykład modyfikacja modyfikatora stawek grupy reklam oznacza typ zasobu AdGroupBidModifier, a zmiana w mniej szczegółowym lub nowszym elemencie podrzędnym może oznaczać element nadrzędny Campaign lub AdGroup.

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

Zmienianie typów stanu

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

Typ zasobu Wartość Identyfikator typu zasobu
Podstawowe podmioty
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
Udostępnione zestawy
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

W przypadku wcześniejszych wersji interfejsu Google Ads API może zwracać wiersze z wartością typu zasobu UNKNOWN, co oznacza, że typ jest obsługiwany w przyszłej wersji interfejsu Google Ads API, ale nie był w pełni obsługiwany w momencie wydania bieżącej wersji. W takiej sytuacji możesz określić typ zasobu wiersza, analizując zwrócony element resource_name.

Format nazwy zasobu to:

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

Może być więcej identyfikatorów oddzielonych znakiem -, ale istotny jest identyfikator resource_type_id – drugi identyfikator po ostatnim ukośniku. W tabeli powyżej znajdują się wszystkie identyfikatory typów zasobów.

Pobieranie zmian

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

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

Zastosowanie zmiany w wynikach stanu zmiany może potrwać do 3 minut.

Zapytanie musi filtrować datę z ostatnich 90 dni i opcjonalnie godzinę oraz musi zawierać klauzulę LIMIT ustawioną na maksymalnie 10 tys. 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.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;
}
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