Targeting

资源定位的管理是 Display & Video 360 API 的核心功能。 定位条件可分配给多种资源类型，并利用多种其他资源和 ID 空间。本页详细介绍了在采用 Display & Video 360 API 分配的定位选项服务时需要注意的限制以及要实施的最佳实践。

利用定位条件继承

分配给某些资源的定位条件可以被其子资源继承。子资源继承的定位选项可检索，但无法在子资源级别修改。这样，系统便会在合作伙伴或广告客户的所有广告中强制执行品牌保障设置和其他定位条件。

继承路径如下图所示：

如图所示，某些定位级别仅支持部分定位类型。这意味着，某些定位选项无法在更高级别设置并继承，而需要在更低级别设置。

YouTube 及合作伙伴资源中的继承

Display & Video 360 API 中的 YouTube 及合作伙伴资源不会反映定位条件继承。广告组继承的定位条件无法在 AdGroup 级别检索，并且分配给父级资源的 YouTube 定位条件不会被子资源继承。

如需检索广告组的所有功能定位设置，您应检索为广告组、父级订单项和父级广告客户分配的定位选项。

注意在创建订单项时分配的定位条件

除了继承的定位选项之外，大多数定位条件只能在订单项创建后分配。不过，有些定位类型在创建订单项时会向订单项分配一组默认值子集。这些定位类型包括：

• TARGETING_TYPE_DEVICE_TYPE
• TARGETING_TYPE_EXCHANGE
• TARGETING_TYPE_ON_SCREEN_POSITION

如果您尝试创建已分配的定位选项或删除不存在的定位选项，系统会返回错误，因此我们建议您了解在创建订单项时分配给其的完整定位套件。如果您需要检索为订单项分配的各类定位条件，请使用 advertisers.lineItems.bulkListAssignedTargetingOptions。

此外，如果未向资源分配相应类型的定位选项，系统会默认设置某些设置。例如，如果资源未定义 TARGETING_TYPE_AUTHORIZED_SELLER_STATUS 定位选项，则表示其使用的是“经授权的直接卖方和转销商”状态。

不要指望自动“默认定位”

在 Display & Video 360 中，在广告系列或广告订单级设置的定位条件不会立即传递给其子级订单项。此类定位条件称为“默认定位条件”，并用作应用于界面中随后创建的订单项的定位条件模板。

在 Display & Video 360 API 中，系统不会自动将默认定位条件应用于新创建的订单项。创建基本订单项时，系统不会复制任何广告系列级或广告订单级定位条件。在这种情况下，必须通过指定的定位选项创建或批量修改方法，分别将定位应用于订单项。

警告： 在 Display & Video 360 API v4 中，您无法再检索或管理广告系列和广告订单级定位条件。

特殊方法可以是例外情况。例如，通过 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 界面或上传结构化数据文件来更新此定位条件。

通过单个选项指定受众群体定位条件

大多数定位类型的定位选项都是单独分配的。受众群体定位条件不遵循此模块化惯例，而是在单个可配置的受众群体定位条件详情对象中分配，该对象会列出投放广告时要包含和排除的受众群体的 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
• advertisers.lineItems.bulkUpdate
• advertisers.lineItems.patch
• advertisers.lineItems.targetingTypes.assignedTargetingOptions.create
• advertisers.lineItems.targetingTypes.assignedTargetingOptions.delete

如果您需要同时为单个订单项添加或移除多个已分配的定位选项，则应使用单个 advertisers.lineItems.bulkEditAssignedTargetingOptions 请求。如果您要更新订单项的设置和定位条件，请将 patch 或 bulkUpdate 请求和相关定位请求加入队列，以确保在第一个请求返回响应之前不会发送第二个请求。