本頁面由 Cloud Translation API 翻譯而成。

指定目標

資源指定功能是 Display & Video 360 API 的核心功能。指定目標可指派給多個資源類型，並使用一些其他資源和 ID 空間。本頁會詳細說明在採用 Display & Video 360 API 指定指定目標選項服務時的相關限制和最佳做法。

沿用指定目標

其子項資源可以繼承指派給某些資源的指定目標。可擷取子項資源繼承的指定目標選項，但無法在子項資源層級編輯。如此一來，就能為整個夥伴或廣告主強制執行品牌安全設定和其他指定目標。

繼承路徑如下圖所示：

指定目標沿用圖表

如圖所示，部分指定目標層級只支援部分指定類型。這表示某些指定目標選項無法在較高層級及繼承層級設定，而必須改在較低層級設定。

YouTube 與合作夥伴資源繼承

Display & Video 360 API 中的 YouTube 與合作夥伴資源不會反映指定目標沿用設定。無法在 AdGroup 層級擷取由廣告群組沿用的指定目標，且子項資源也不會沿用父項資源的 YouTube 指定目標。

如要擷取廣告群組的所有功能指定目標設定，建議您擷取廣告群組、上層委刊項和上層廣告客戶指定的指定目標選項。

瞭解在建立委刊項時指派的指定目標

除了沿用的指定目標選項以外，大多數指定目標都必須在建立委刊項後才能指派。不過，有幾種指定類型會在建立委刊項時，指派給委刊項的預設值子集。這些指定類型如下：

嘗試建立現有或刪除現有的指定選項時，會傳回錯誤，因此建議您瞭解在建立委刊項時，指派給委刊項的完整指定套件。如果您需要擷取指派給不同指定類型委刊項的指定目標，請使用 advertisers.lineItems.bulkListAssignedTargetingOptions。

此外，系統預設會在資源沒有指派該類型的指定選項時設定某些設定。舉例來說，如果資源未定義 TARGETING_TYPE_AUTHORIZED_SELLER_STATUS 指定選項，表示資源使用的是「授權直接賣方和經銷商」狀態。

請勿使用自動「預設指定目標」

在 Display & Video 360 中，廣告活動或廣告訂單層級設定的指定目標不會立即傳遞至子委刊項。這個指定目標稱為「預設指定目標」，做為指定範本使用，並套用至後續在 UI 中建立的委刊項。

在 Display & Video 360 API 中，系統不會自動將預設指定目標套用到新建立的委刊項。建立基本委刊項不會複製任何廣告活動或廣告訂單層級指定目標。在這種情況下，您必須透過指派的指定選項建立或大量編輯方法，將所需的指定目標分別套用到委刊項。

特殊方法可以是例外狀況。舉例來說，透過 advertisers.lineItems.generateDefault 建立的委刊項會複製上層廣告訂單的設定，包括指派的指定目標。同樣地，透過複製功能建立的委刊項會獲得與原始委刊項相同的指定目標。

無法修改 YouTube 與合作夥伴指定目標

您無法使用 Display & Video 360 API 更新 YouTube 與合作夥伴廣告活動專用的指定目標。

YouTube 與合作夥伴指定目標包含直接指派給 YouTube 與合作夥伴委刊項和廣告群組的所有指定目標，以及下列指定類型的任何指定目標：

TARGETING_TYPE_SESSION_POSITION
TARGETING_TYPE_YOUTUBE_CHANNEL
TARGETING_TYPE_YOUTUBE_VIDEO

您可以直接透過 Display & Video 360 UI 或上傳結構化資料檔案來更新指定目標。

只用一個選項指定目標對象

系統會分別指派大部分指定類型的指定目標選項。指定目標對象群組指定目標不會遵循這個模組化慣例，而是在可設定的單一目標對象區隔指定詳細資料物件中指派，該物件會列出放送廣告時要納入及排除的目標對象 ID。指定這個目標對象群組選項的 assignedTargetingOptionId 後，一律為「audienceGroup」。

這種設計意味著，如要對指定目標對象群組進行任何變更，您必須先刪除現有的指定目標對象群組指定選項，然後根據所需變更建立新的目標對象群組指定選項。只要使用 advertisers.lineItems.bulkEditAssignedTargetingOptions，即可在單一要求中完成這項操作。

以下範例說明如何更新指定目標對象，以便明確指定其他 Google 目標對象：

Java

long advertiserId = advertiser-id;
long lineItemId = line-item-id
List<Long> addedGoogleAudienceIds =
    Arrays.asList(google-audience-id-to-add,...);

// Build Google audience targeting settings objects to add to audience
// targeting.
ArrayList<GoogleAudienceTargetingSetting> newGoogleAudienceSettings =
    new ArrayList<GoogleAudienceTargetingSetting>();

// Convert list of Google Audience IDs into list of settings.
for (Long googleAudienceId : addedGoogleAudienceIds) {
  newGoogleAudienceSettings.add(new GoogleAudienceTargetingSetting()
      .setGoogleAudienceId(googleAudienceId));
}

// Create relevant bulk edit request objects.
BulkEditLineItemAssignedTargetingOptionsRequest requestContent =
    new BulkEditLineItemAssignedTargetingOptionsRequest();
AudienceGroupAssignedTargetingOptionDetails updatedAudienceGroupDetails;
ArrayList<DeleteAssignedTargetingOptionsRequest> audienceGroupDeleteRequests =
    new ArrayList<DeleteAssignedTargetingOptionsRequest>();

try {
  // Retrieve existing audience group targeting.
  AssignedTargetingOption existingAudienceGroupTargetingOption =
      service
          .advertisers()
          .lineItems()
          .targetingTypes()
          .assignedTargetingOptions()
          .get(
              advertiserId,
              lineItemId,
              "TARGETING_TYPE_AUDIENCE_GROUP",
              "audienceGroup"
          ).execute();

  // Extract existing audience group targeting details.
  updatedAudienceGroupDetails =
      existingAudienceGroupTargetingOption.getAudienceGroupDetails();

  // Build and add delete request for existing audience group targeting.
  ArrayList<String> deleteAudienceGroupAssignedTargetingIds =
      new ArrayList<String>();
  deleteAudienceGroupAssignedTargetingIds.add("audienceGroup");

  audienceGroupDeleteRequests
      .add(new DeleteAssignedTargetingOptionsRequest()
          .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP")
          .setAssignedTargetingOptionIds(
              deleteAudienceGroupAssignedTargetingIds
          )
      );
}
catch (GoogleJsonResponseException e) {
  updatedAudienceGroupDetails =
      new AudienceGroupAssignedTargetingOptionDetails();
}

// Set delete requests in edit request.
requestContent.setDeleteRequests(audienceGroupDeleteRequests);

// Construct new group of Google Audiences to include in targeting.
GoogleAudienceGroup updatedIncludedGoogleAudienceGroup =
    updatedAudienceGroupDetails.getIncludedGoogleAudienceGroup();
if (updatedIncludedGoogleAudienceGroup != null) {
  List<GoogleAudienceTargetingSetting> updatedGoogleAudienceSettings =
      updatedIncludedGoogleAudienceGroup.getSettings();
  updatedGoogleAudienceSettings.addAll(newGoogleAudienceSettings);
  updatedIncludedGoogleAudienceGroup
      .setSettings(updatedGoogleAudienceSettings);
} else {
  updatedIncludedGoogleAudienceGroup = new GoogleAudienceGroup();
  updatedIncludedGoogleAudienceGroup.setSettings(newGoogleAudienceSettings);
}

// Add new Google Audience group to audience group targeting details.
updatedAudienceGroupDetails
    .setIncludedGoogleAudienceGroup(updatedIncludedGoogleAudienceGroup);

// Create new targeting option to assign.
AssignedTargetingOption newAudienceGroupTargeting =
    new AssignedTargetingOption();
newAudienceGroupTargeting
    .setAudienceGroupDetails(updatedAudienceGroupDetails);

// Build audience group targeting create request and add to list of create
// requests.
ArrayList<AssignedTargetingOption> createAudienceGroupAssignedTargetingOptions =
    new ArrayList<AssignedTargetingOption>();
createAudienceGroupAssignedTargetingOptions.add(newAudienceGroupTargeting);
ArrayList<CreateAssignedTargetingOptionsRequest> targetingCreateRequests =
    new ArrayList<CreateAssignedTargetingOptionsRequest>();
targetingCreateRequests.add(new CreateAssignedTargetingOptionsRequest()
    .setTargetingType("TARGETING_TYPE_AUDIENCE_GROUP")
    .setAssignedTargetingOptions(
        createAudienceGroupAssignedTargetingOptions
    )
);

// Set create requests in edit request.
requestContent.setCreateRequests(targetingCreateRequests);

// Configure and execute the bulk list request.
BulkEditLineItemAssignedTargetingOptionsResponse response =
    service.advertisers().lineItems()
        .bulkEditLineItemAssignedTargetingOptions(
            advertiserId,
            lineItemId,
            requestContent).execute();

Python

advertiser_id = advertiser-id
line_item_id = line-item-id
added_google_audiences = [google-audience-id-to-add,...]

# Build Google audience targeting settings objects to create.
new_google_audience_targeting_settings = []
for google_audience_id in added_google_audiences:
 new_google_audience_targeting_settings.append(
     {'googleAudienceId': google_audience_id}
 )

# Retrieve any existing line item audience targeting.
retrieved_audience_targeting = service.advertisers().lineItems(
).targetingTypes().assignedTargetingOptions().get(
   advertiserId=advertiser_id,
   lineItemId=line_item_id,
   targetingType="TARGETING_TYPE_AUDIENCE_GROUP",
   assignedTargetingOptionId="audienceGroup"
).execute()

updated_audience_group_details = {}

# Copy over any existing audience targeting.
if 'audienceGroupDetails' in retrieved_audience_targeting:
 updated_audience_group_details = retrieved_audience_targeting[
     'audienceGroupDetails']

# Append the new Google audience IDs to any existing positive Google
# audience targeting.
if 'includedGoogleAudienceGroup' in updated_audience_group_details:
 updated_audience_group_details[
     'includedGoogleAudienceGroup']['settings'].extend(
         new_google_audience_targeting_settings)
else:
 updated_audience_group_details['includedGoogleAudienceGroup'] = {
     'settings': new_google_audience_targeting_settings
 }

# Build bulk edit request.
bulk_edit_request = {
   'deleteRequests': [
       {
         'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP",
         'assignedTargetingOptionIds': [
           "audienceGroup"
         ]
       }
   ],
   'createRequests': [
       {
           'targetingType': "TARGETING_TYPE_AUDIENCE_GROUP",
           'assignedTargetingOptions': [
               {'audienceGroupDetails': updated_audience_group_details}
           ]
       }
   ]
}

# Update the audience targeting
updated_audience_targeting = service.advertisers().lineItems(
).bulkEditLineItemAssignedTargetingOptions(
   advertiserId=advertiser_id,
   lineItemId=line_item_id,
   body=bulk_edit_request
).execute()

PHP

$advertiserId = advertiser-id;
$lineItemId = line-item-id;
$addedGoogleAudienceIds = array(google-audience-id-to-add,...);

// Convert list of Google Audience IDs into list of Google audience
// settings.
$newGoogleAudienceSettings = array();
foreach ($addedGoogleAudienceIds as $googleAudienceId) {
    $newSetting =
        new Google_Service_DisplayVideo_GoogleAudienceTargetingSetting();
    $newSetting->setGoogleAudienceId($googleAudienceId);
    $newGoogleAudienceSettings[] = $newSetting;
}

// Create a bulk edit request.
$requestBody =
    new Google_Service_DisplayVideo_BulkEditLineItemAssignedTargetingOptionsRequest();

$audienceGroupDeleteRequests = array();

try {
    // Retrieve existing audience group targeting.
    $existingAudienceGroupTargetingOption = $this
        ->service
        ->advertisers_lineItems_targetingTypes_assignedTargetingOptions
        ->get(
            $advertiserId,
            $lineItemId,
            'TARGETING_TYPE_AUDIENCE_GROUP',
            'audienceGroup'
        );

    // Extract existing audience group targeting details.
    $updatedAudienceGroupDetails =
        $existingAudienceGroupTargetingOption
            ->getAudienceGroupDetails();

    // Build and add delete request for existing audience group
    // targeting.
    $deleteAudienceGroupAssignedTargetingIds = array();
    $deleteAudienceGroupAssignedTargetingIds[] = "audienceGroup";

    $audienceGroupDeleteRequest =
        new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest();
    $audienceGroupDeleteRequest
        ->setTargetingType('TARGETING_TYPE_AUDIENCE_GROUP');
    $audienceGroupDeleteRequest
        ->setAssignedTargetingOptionIds(
            $deleteAudienceGroupAssignedTargetingIds
        );
    $audienceGroupDeleteRequests[] = $audienceGroupDeleteRequest;
} catch (\Exception $e) {
    $updatedAudienceGroupDetails =
        new Google_Service_DisplayVideo_AudienceGroupAssignedTargetingOptionDetails();
}

// Set delete requests in edit request.
$requestBody->setDeleteRequests($audienceGroupDeleteRequests);

// Construct new group of Google audiences to include in targeting.
$updatedIncludedGoogleAudienceGroup = $updatedAudienceGroupDetails
    ->getIncludedGoogleAudienceGroup();

if (!empty($updatedIncludedGoogleAudienceGroup)) {
    // Get existing settings.
    $updatedGoogleAudienceSettings =
    $updatedIncludedGoogleAudienceGroup->getSettings();

    // Add new Google audiences to existing list.
    $updatedGoogleAudienceSettings = array_merge(
        $updatedGoogleAudienceSettings,
        $newGoogleAudienceSettings
    );

    // Set updated Google audience list.
    $updatedIncludedGoogleAudienceGroup
        ->setSettings($updatedGoogleAudienceSettings);
} else {
    // Create new Google audience group.
    $updatedIncludedGoogleAudienceGroup =
        new Google_Service_DisplayVideo_GoogleAudienceGroup();

    // Set list of new Google audiences for targeting.
    $updatedIncludedGoogleAudienceGroup
        ->setSettings($newGoogleAudienceSettings);
}

// Add new Google Audience group to audience group targeting details.
$updatedAudienceGroupDetails
    ->setIncludedGoogleAudienceGroup(
        $updatedIncludedGoogleAudienceGroup
    );

// Create new targeting option to assign.
$newAudienceGroupTargeting =
    new Google_Service_DisplayVideo_AssignedTargetingOption();
$newAudienceGroupTargeting
    ->setAudienceGroupDetails($updatedAudienceGroupDetails);

// Build audience group targeting create request and add to list of
// create requests.
$createAudienceGroupAssignedTargetingOptions = array();
$createAudienceGroupAssignedTargetingOptions[] =
    $newAudienceGroupTargeting;
$createAudienceGroupTargetingRequest =
    new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest();
$createAudienceGroupTargetingRequest->setTargetingType(
    "TARGETING_TYPE_AUDIENCE_GROUP"
);
$createAudienceGroupTargetingRequest->setAssignedTargetingOptions(
    $createAudienceGroupAssignedTargetingOptions
);
$createRequests[] = $createAudienceGroupTargetingRequest;

// Set create requests in edit request.
$requestBody->setCreateRequests($createRequests);

// Call the API, editing the assigned targeting options for the
// identified line item.
$response = $this
    ->service
    ->advertisers_lineItems
    ->bulkEditLineItemAssignedTargetingOptions(
        $advertiserId,
        $lineItemId,
        $requestBody
    );

為即將淘汰的指定目標選項做好準備

指定目標選項不是靜態的，而且有一小部分可能會不時淘汰。指定目標選項已淘汰後，並不會影響委刊項的廣告放送。淘汰後，系統會從現有委刊項中取消指派這些選項，而嘗試擷取或指派這些選項的請求會導致錯誤。

為了避免發生這些錯誤，建議您定期檢查已儲存的指定選項 ID。為節省配額，我們建議您快取常用的 ID。但是，儲存 ID 表示指定選項可能已淘汰。因此，建議您定期使用 targetingOptions.targetingTypes.get 擷取所有已儲存的指定目標選項 ID，確認 Display & Video 360 仍支援這些 ID。

如要進一步瞭解重要的先前和即將淘汰項目，請參閱「公告淘汰」頁面。

請勿提出並行要求更新相同的委刊項

如果嘗試使用多個並行要求更新設定或指派的指定目標，將會傳回錯誤。適用的要求包括：

如果您需要同時為單一委刊項新增或移除多個指派的指定目標選項，請使用單一 advertisers.lineItems.bulkEditAssignedTargetingOptions 要求。如要更新委刊項的設定和指定目標，請將 patch 或 bulkUpdate 要求和相關指定目標要求排入佇列，以確保在第一個傳回回應之前，系統不會傳送第二個請求。