상태 변경

동영상: 상태

변경 상태는 일정 기간 동안 계정 내에서 변경된 리소스를 추적하는 방법을 제공합니다. 특정 기간 동안 한 리소스에 여러 변경사항이 있는 경우 가장 최근의 변경사항만 반환됩니다. 그런 다음 로컬 데이터베이스 값을 기간 내에 변경된 값과 동기화해야 하는지 여부를 결정할 수 있습니다.

예를 들어 지정된 기간 동안 특정 캠페인을 추가한 후 업데이트하면 ADD 작업이 아닌 UPDATE의 변경 상태만 반환됩니다. 기간의 끝을 업데이트 이전으로 옮기면 ADD 작업이 표시됩니다.

변경 내역 웹페이지와 유사한 세부정보 뷰가 있는 완전한 필드별 결과를 얻으려면 이벤트 변경을 참조하세요.

상태 유형 변경

다음 리소스 유형이 추적됩니다. 리소스 유형 ID는 ChangeStatusResourceType의 열거형 값 색인과 다릅니다.

리소스 유형 리소스 유형 ID
핵심 항목
광고그룹 AD_GROUP 2
광고그룹 광고 AD_GROUP_AD 3
광고그룹 입찰가 조정 AD_GROUP_BID_MODIFIER 11
광고그룹 기준 AD_GROUP_CRITERION 4
광고그룹 피드 AD_GROUP_FEED 12
실행 캠페인 5
캠페인 기준 CAMPAIGN_CRITERION 6
피드
캠페인 피드 CAMPAIGN_FEED 9
피드 피드 8
피드 항목 FEED_ITEM 10
공유 세트
공유 조합 SHARED_SET 17
캠페인 공유 조합 CAMPAIGN_SHARED_SET 18
애셋
저작물 애셋 13
고객 애셋 CUSTOMER_ASSET 14
캠페인 확장 소재 CAMPAIGN_ASSET 15
광고그룹 애셋 AD_GROUP_ASSET 16

ID로 리소스 유형 결정

이전 API 버전의 경우 Google Ads API가 UNKNOWN 리소스 유형 값이 있는 행을 반환할 수 있습니다. 즉, 이 유형은 Google Ads API의 향후 버전에서는 지원되지만 현재 버전이 출시되었을 때는 완전히 지원되지 않았습니다. 이 경우에도 반환된 resource_name를 파싱하여 행의 리소스 유형을 확인할 수 있습니다.

리소스 이름 형식은 다음과 같습니다.

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

- 문자로 구분된 하나 이상의 추가 ID가 있을 수 있지만 관련된 ID는 마지막 슬래시 뒤의 두 번째 ID인 resource_type_id입니다. 이전 표에는 모든 리소스 유형 ID가 나와 있습니다.

변경사항 가져오기

변경사항 목록은 날짜 및 리소스 유형별로 필터링할 수 있습니다. 지정된 리소스에 대한 작업은 ADDED, CHANGED, REMOVED 중 하나입니다.

모든 리소스 유형의 모든 변경사항 목록을 검색할 수 있습니다. 반환된 resource_type는 변경된 필드입니다. 모든 상위 필드도 채워집니다. 예를 들어 ad_group_criterion이 변경되면 ad_group 필드도 채워집니다.

변경사항이 변경 상태 결과에 반영되기까지 최대 3분이 걸릴 수 있습니다.

쿼리는 지난 90일 이내의 날짜(선택적으로 시간)를 필터링해야 하며 최대 10,000개의 결과로 설정된 LIMIT 절을 포함해야 합니다.

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;
}
      

2,399필리핀

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 "";
  }
}
      

로컬에서 동기화

정확한 resource_name를 가져온 후에는 이 리소스 이름으로 새 쿼리를 실행하여 리소스의 모든 현재 값을 가져와야 합니다. 특정 리소스의 변경된 값에 대한 변경 상태는 추적되지 않고 변경된 리소스만 추적합니다. 이전 값과 현재 값의 차이를 결정하는 것은 호출 프로그램의 책임입니다.

시간 변경

last_change_date_time 필드는 가장 최근에 리소스가 변경된 시기를 나타냅니다. 따라서 로컬에 캐시된 데이터의 최신성을 이 필드의 값과 비교하여 로컬 데이터가 최신이 아닌지 확인할 수 있습니다.

이 필드는 필터링 가능합니다. 즉, Google Ads 쿼리 언어 (GAQL) 쿼리의 WHERE 절에서 사용할 수 있으므로 지정된 시간 이전 또는 이후에 발생한 리소스의 변경사항을 쿼리할 수 있습니다.

예를 들어 지난주에 특정 리소스 유형에 대해 발생한 모든 변경사항을 찾으려면 다음 GAQL 조건자 절을 사용하면 됩니다.

WHERE change_status.last_change_date_time DURING LAST_7_DAYS