Display & Video 360 API 中会结合使用定位选项、指定的定位选项和订单项服务来设置订单项定位。本页面介绍并举例说明了如何查找可用的定位选项、为订单项分配定位选项,以及如何对订单项执行批量操作以列出和修改指定的定位选项。
查找可用的定位选项
定位选项使用用户指定的变量、现有的可定位实体或现有选项来定义所需的目标受众群体。系统会使用枚举值或定位选项 ID 来标识预先存在的选项,具体取决于定位类型。可定位的实体使用其实体 ID 进行标识。您可以使用 Display & Video 360 API 查找定位选项 ID 和实体 ID。
使用已设置的枚举值
以下定位类型的定位选项是使用特定枚举类型分配的:
TargetingType |
枚举 |
---|---|
TARGETING_TYPE_AGE_RANGE |
AgeRange |
TARGETING_TYPE_CONTENT_INSTREAM_POSITION |
ContentInstreamPosition |
TARGETING_TYPE_CONTENT_OUTSTREAM_POSITION |
ContentOutstreamPosition |
TARGETING_TYPE_DEVICE_TYPE |
DeviceType |
TARGETING_TYPE_DIGITAL_CONTENT_LABEL_EXCLUSION |
ContentRatingTier |
TARGETING_TYPE_ENVIRONMENT |
Environment |
TARGETING_TYPE_EXCHANGE |
Exchange |
TARGETING_TYPE_GENDER |
Gender |
TARGETING_TYPE_HOUSEHOLD_INCOME |
HouseholdIncome |
TARGETING_TYPE_NATIVE_CONTENT_POSITION |
NativeContentPosition |
TARGETING_TYPE_OMID |
Omid |
TARGETING_TYPE_PARENTAL_STATUS |
ParentalStatus |
TARGETING_TYPE_SENSITIVE_CATEGORY_EXCLUSION |
SensitiveCategory |
TARGETING_TYPE_VIDEO_PLAYER_SIZE |
VideoPlayerSize |
TARGETING_TYPE_VIEWABILITY |
Viewability |
相关枚举值的字符串版本可用于识别这些定位类型的现有 AssignedTargetingOption
资源,并在 assignedTargetingOptionIdAlias
字段中提供。在检索或删除已分配的定位选项时,您可以使用此别名值代替 assignedTargetingOptionId
。
检索定位选项 ID
使用现有选项的定位方式是通过相应的定位选项 ID 进行分配的。
例如,屏幕上的位置数量有限,可以使用定位类型 TARGETING_TYPE_ON_SCREEN_POSITION
进行定位。每个位置都有对应的定位选项 ID。
这些定位选项 ID 可通过定位选项服务检索。根据定位类型,可通过以下两种方式之一进行检索:
- 个别检索或详尽的列表:可以使用
get
和list
方法来检索大多数定位类型的选项。使用targetingTypes.targetingOptions.get
可检索由定位类型和定位选项 ID 标识的定位选项的详细信息。使用targetingTypes.targetingOptions.list
可列出指定定位类型的所有可用定位选项。 - 搜索:必须使用
search
方法检索基于地理位置的定位类型(TARGETING_TYPE_GEO_REGION
、TARGETING_TYPE_POI
和TARGETING_TYPE_BUSINESS_CHAIN
)的选项。使用targetingTypes.targetingOptions.search
可检索与指定查询字符串匹配的指定类型的定位选项。
以下示例展示了如何检索定位类型 TARGETING_TYPE_BROWSER
的可能定位选项列表:
Java
// Configure the list request. TargetingOptions.List request = service .targetingTypes() .targetingOptions() .list("TARGETING_TYPE_BROWSER") .setAdvertiserId(advertiser-id); // Create the response and nextPageToken variables. ListTargetingOptionsResponse response; String nextPageToken = null; do { // Create and execute the list request. response = request.setPageToken(nextPageToken).execute(); // Check if the response is empty. if (response.isEmpty()) { System.out.print("List request returned no Targeting Options"); break; } // Iterate over retrieved targeting options. for (TargetingOption option : response.getTargetingOptions()) { System.out.printf( "Targeting Option ID: %s, Browser Display Name: '%s'\n", option.getTargetingOptionId(), option.getBrowserDetails().getDisplayName()); } // Update the next page token. nextPageToken = response.getNextPageToken(); } while (!Strings.isNullOrEmpty(nextPageToken));
Python
# Create the page token variable. next_page_token = "" while True: # Request the targeting options list. response = service.targetingTypes() \ .targetingOptions().list( advertiserId=advertiser-id, targetingType="TARGETING_TYPE_BROWSER", pageToken=next_page_token ).execute() # Check if response is empty. if not response: print("List request returned no Targeting Options") break # Iterate over retrieved targeting options. for option in response['targetingOptions']: print("Targeting Option ID: %s, Browser Display Name: %s" % (option['targetingOptionId'], option['browserDetails']['displayName'])) # Break out of loop if there is no next page. if 'nextPageToken' not in response: break # Update the next page token. next_page_token = response['nextPageToken']
PHP
// Create the page token variable. $nextPageToken = null; do { // Build the query parameters object for the request. $optParams = array( 'advertiserId' => advertiser-id, 'pageToken' => $nextPageToken ); // Call the API, getting the browser targeting options for the // identified advertiser. $response = $this ->service ->targetingTypes_targetingOptions ->listTargetingTypesTargetingOptions( 'TARGETING_TYPE_BROWSER', $optParams ); // Print the resulting targeting options. if (!empty($response->getTargetingOptions())) { foreach ($response->getTargetingOptions() as $option) { printf( 'Targeting Option ID: %s, Browser Display Name: %s\n', $option['targetingOptionId'], $option['browserDetails']['displayName'] ); } } else { print('No targeting options returned\n'); } // Update the next page token. $nextPageToken = $response->getNextPageToken(); } while ( !empty($response->getTargetingOptions()) && $nextPageToken );
列出可定位的实体
要使用现有的可定位实体定位订单项,您需要该实体的 ID。可定位的实体(例如渠道、组合的受众群体和广告资源来源组)可在 Display & Video 360 API 中通过各自的服务检索到。
每项服务都有自己的 get
和 list
方法。使用 get
方法确认给定广告主下是否有实体。使用 list
方法可以发现给定广告客户可用的该资源类型的所有实体,从而发现这些实体可用于向该广告客户下的订单项分配定位条件。
您还可以通过该 API 管理一部分可定位实体。这是通过相应服务中的 create
和 patch
方法,以及针对实体中列出的各个值(如广告资源来源、否定关键字和位置)的服务实现的。
构建地图注点定位选项 ID
您可以使用 targetingTypes.targetingOptions.search
检索 TARGETING_TYPE_POI
下的已命名地图注点定位选项。此外,您还可以构建定制的 TARGETING_TYPE_POI
定位选项 ID,以便定位特定的经纬度坐标。
要构建地图注点定位选项 ID,请按以下步骤操作:
- 检索经纬度坐标(例如:“40.7414691, -74.003387”)
- 将坐标值四舍五入到小数点后六位(例如:“40.741469, -74.003387”)
- 移除坐标值中的小数位(例如:“40741469、-74003387”)
- 将两个值串联成一个字符串,多个字符串之间用英文分号分隔(例如:“40741469;-74003387”)
在创建已分配 TARGETING_TYPE_POI
的定位选项时,可将生成的字符串用作 targetingOptionId
。
创建后,已分配定位选项资源的 targetingOptionId
和 assignedTargetingOptionId
字段将更新,并附加分号和字母数字哈希值。
指定定位选项
向订单项分配的定位条件表示为已分配的定位选项。您可以使用已分配的定位选项服务来管理这些实体。创建分配的定位选项后,系统会将这些定位详细信息应用于父级订单项。删除已分配的现有定位选项会移除该定位条件。
使用 advertisers.lineItems.targetingTypes.assignedTargetingOptions.create
创建指定的定位选项。在已分配的定位选项资源的 details
字段中指定与其预期定位类型相对应的定位参数。
下例说明了如何创建定位类型为 TARGETING_TYPE_BROWSER
的已分配定位选项:
Java
// Create an AssignedTargetingOption object of the // browser targeting type. AssignedTargetingOption assignedTargetingOption = new AssignedTargetingOption() .setBrowserDetails( new BrowserAssignedTargetingOptionDetails() .setTargetingOptionId(targeting-option-id)); // Configure the create request. AssignedTargetingOptions.Create request = service .advertisers() .lineItems() .targetingTypes() .assignedTargetingOptions() .create( advertiser-id, line-item-id, "TARGETING_TYPE_BROWSER", assignedTargetingOption); // Send the request. AssignedTargetingOption response = request.execute(); // Display the new assigned targeting option. System.out.printf("AssignedTargetingOption %s was created.", response.getName());
Python
# Create a assigned targeting option object. assigned_targeting_option_obj = { 'browserDetails': { 'targetingOptionId': targeting-option-id } } # Create the assigned targeting option. assigned_targeting_option = service.advertisers().lineItems()\ .targetingTypes().assignedTargetingOptions().create( advertiserId=advertiser-id, lineItemId=line-item-id, targetingType="TARGETING_TYPE_BROWSER", body=assigned_targeting_option_obj ).execute() # Display the new assigned targeting option. print("Assigned Targeting Option %s was created." % assigned_targeting_option["name"])
PHP
// Create a assigned targeting option object. $assignedTargetingOption = new Google_Service_DisplayVideo_AssignedTargetingOption(); // Create and set browser details. $details = new Google_Service_DisplayVideo_BrowserAssignedTargetingOptionDetails(); $details->setTargetingOptionId(targeting-option-id); $assignedTargetingOption->setBrowserDetails($details); // Call the API, creating the browser assigned targeting option for the // given line item. $result = $this ->service ->advertisers_lineItems_targetingTypes_assignedTargetingOptions ->create( advertiser-id, line-item-id, 'TARGETING_TYPE_BROWSER', $assignedTargetingOption ); printf( 'Assigned Targeting Option %s was created.\n', $result['name'] );
错误数
定位配置错误
Display & Video 360 中有许多关于定位的复杂规则。在 Display & Video 360 API 中,系统会通过创建已分配的定位选项时返回错误来强制执行这些规则。API 返回的错误会指明违规行为。
错误主要是由已分配到订单项的现有定位条件导致的。使用 advertisers.lineItems.targetingTypes.assignedTargetingOptions.list
可检索为订单项分配的指定定位类型的所有定位选项,根据限制评估能否使用所需的定位条件;使用 advertisers.lineItems.targetingTypes.assignedTargetingOptions.delete
可移除所有不需要的定位条件,然后再次尝试创建已分配的所需定位选项。
YouTube 及合作伙伴定位错误
无法使用 Display & Video 360 API 更新 YouTube 及合作伙伴广告系列的专属定位条件,尝试这样做会导致错误。
YouTube 及合作伙伴定位条件包含直接分配给 YouTube 及合作伙伴订单项和广告组的所有定位条件,以及以下定位类型的所有定位条件:
TARGETING_TYPE_SESSION_POSITION
TARGETING_TYPE_YOUTUBE_CHANNEL
TARGETING_TYPE_YOUTUBE_VIDEO
并发错误
如果尝试通过多个并发请求更新单个订单项的设置或定位条件,则会导致错误。
如果您需要同时为单个订单项添加或移除多个已分配的定位选项,则应使用批量修改请求。如果您要更新订单项的设置和定位条件,请连续发出 advertisers.lineItems.patch
请求和相关定位请求,以确保在第一个请求返回响应之前不会发送第二个请求。
批量定位和资源范围的定位操作
您可以使用批量定位和资源级定位方法来跨各种定位类型管理已分配的定位选项:
- 您可以使用批量定位方式在多个定位资源下检索或修改定位选项。您可以使用
advertisers.lineItems.bulkListAssignedTargetingOptions
获取多个订单项的完整定位配置,也可以使用advertisers.lineItems.bulkEditAssignedTargetingOptions
对多个订单项的定位条件进行相同的更新。这些依赖项仅在advertisers.lineItems
服务中提供。 - 使用资源级定位方式可以检索或修改单个资源下多种定位类型的定位选项。这些依赖项在
partners
、advertisers
、advertisers.campaigns
和advertisers.insertionOrders
服务中提供,分别命名为listAssignedTargetingOptions
或editAssignedTargetingOptions
。
如果您想全面了解订单项的当前定位条件,想要对订单项应用预设的定位配置,或者需要同时对订单项的定位条件进行多项更改,不妨考虑使用以下定位方式。
批量定位列表
advertisers.lineItems.bulkListAssignedTargetingOptions
可用于查看通过不同的定位类型分配给一个或多个订单项的所有定位条件。其运行方式与任何其他 list
方法类似。您可以使用 filter
查询参数,按 TargetingType
或 Inheritance
过滤结果。
下例说明了如何列出已分配给订单项且父级合作伙伴或广告客户沿用的所有定位选项:
Java
// Configure the bulk list request. LineItems.BulkListAssignedTargetingOptions request = service.advertisers().lineItems() .bulkListAssignedTargetingOptions(advertiser-id); // Set Line Items to retrieve targeting for. request.setLineItemIds(line-item-ids); // Set filter to only return inherited assigned targeting options. request.setFilter( "inheritance=\"INHERITED_FROM_ADVERTISER\" OR inheritance=\"INHERITED_FROM_PARTNER\""); // Create the response and nextPageToken variables. BulkListAssignedTargetingOptionsResponse response; String nextPageToken = null; do { // Set page token and execute the list request. response = request.setPageToken(nextPageToken).execute(); // Check if the response is empty. if (response.isEmpty()) { System.out.print("Bulk list request returned no Assigned Targeting Options"); break; } // Iterate over retrieved line item assigned targeting option wrapper objects. for (LineItemAssignedTargetingOption lineItemAssignedTargetingOption : response.getLineItemAssignedTargetingOptions()) { System.out.printf( "Assigned Targeting Option %s found\n", lineItemAssignedTargetingOption.getAssignedTargetingOption().getName()); } // Update the next page token. nextPageToken = response.getNextPageToken(); } while (!Strings.isNullOrEmpty(nextPageToken));
Python
# Create the page token variable. next_page_token = "" while True: # Execute the list request. response = service.advertisers().lineItems() \ .bulkListAssignedTargetingOptions( advertiserId=advertiser-id, lineItemIds=line-item-ids, filter="inheritance=\"INHERITED_FROM_ADVERTISER\" OR " "inheritance=\"INHERITED_FROM_PARTNER\"", pageToken=next_page_token ).execute() # Check if response is empty. if not response: print("Bulk list request returned no Assigned Targeting Options") break # Iterate over retrieved assigned targeting options. for lineItemAssignedTargetingOption in response['lineItemAssignedTargetingOptions']: print("Assigned Targeting Option %s found" % (lineItemAssignedTargetingOption['assignedTargetingOption']['name'])) # Break out of loop if there is no next page. if 'nextPageToken' not in response: break # Update the next page token. next_page_token = response['nextPageToken']
PHP
// Create the page token variable. $nextPageToken = null; do { // Build the query parameters object for the request. $optParams = array( 'lineItemIds' => line-item-ids, 'filter' => "inheritance=\"INHERITED_FROM_ADVERTISER\" OR " . "inheritance=\"INHERITED_FROM_PARTNER\"", 'pageToken' => $nextPageToken ); // Call the API, getting all the assigned targeting options for the // identified line item. $response = $service ->advertisers_lineItems ->bulkListAssignedTargetingOptions( advertiser-id, $optParams ); // Print the returned assigned targeting options. if (!empty($response->getLineItemAssignedTargetingOptions())) { foreach ($response->getLineItemAssignedTargetingOptions() as $option) { printf('Assigned Targeting Option %s found\n', $option->getAssignedTargetingOption()['name']); } } else { print('No targeting options returned\n'); } // Update the next page token. $nextPageToken = $response->getNextPageToken(); } while ( !empty($response->getLineItemAssignedTargetingOptions()) && $nextPageToken);
批量修改定位条件
通过 advertisers.lineItems.bulkEditAssignedTargetingOptions
,您可以在一个或多个订单项中同时添加和移除各种定位类型的多个定位选项。
该方法接受 DeleteAssignedTargetingOptionsRequests
列表和 CreateAssignedTargetingOptionsRequests
列表作为参数。单个请求对象可以表示删除或创建多个具有相同定位类型的指定定位选项。
如果尝试删除或创建指定的定位选项导致订单项出错,系统会放弃针对该订单项的批量操作。该请求会返回已成功更新的订单项列表、未能更新的订单项和相关错误的列表。
下面举例说明了如何针对一个或多个订单项批量修改已分配的定位选项,且已指定要删除的定位选项列表和要创建的定位选项:
Java
// Create a bulk edit request. BulkEditAssignedTargetingOptionsRequest requestContent = new BulkEditAssignedTargetingOptionsRequest(); // Set line item IDs in edit request. requestContent.setLineItemIds(line-item-ids); // Build delete request list. ArrayList<DeleteAssignedTargetingOptionsRequest> deleteRequests = new ArrayList<DeleteAssignedTargetingOptionsRequest>(); // Add browser assigned targeting option IDs to delete request list. deleteRequests.add(new DeleteAssignedTargetingOptionsRequest() .setTargetingType("TARGETING_TYPE_BROWSER") .setAssignedTargetingOptionIds(delete-browser-assigned-targeting-ids)); // Add device make or model assigned targeting option IDs to delete request list. deleteRequests.add(new DeleteAssignedTargetingOptionsRequest() .setTargetingType("TARGETING_TYPE_DEVICE_MAKE_MODEL") .setAssignedTargetingOptionIds( delete-device-make-model-assigned-targeting-ids)); // Set delete requests in edit request. requestContent.setDeleteRequests(deleteRequests); // Build create request list. ArrayList<CreateAssignedTargetingOptionsRequest> createRequests = new ArrayList<CreateAssignedTargetingOptionsRequest>(); // Create browser assigned targeting option create request. CreateAssignedTargetingOptionsRequest createBrowserTargetingRequest = new CreateAssignedTargetingOptionsRequest(); createBrowserTargetingRequest.setTargetingType("TARGETING_TYPE_BROWSER"); // Create and set list of browser assigned targeting options. ArrayList<AssignedTargetingOption> createBrowserAssignedTargetingOptions = new ArrayList<AssignedTargetingOption>(); for (String targetingOptionId : create-browser-assigned-targeting-ids) { createBrowserAssignedTargetingOptions.add(new AssignedTargetingOption() .setBrowserDetails( new BrowserAssignedTargetingOptionDetails() .setTargetingOptionId(targetingOptionId))); } createBrowserTargetingRequest .setAssignedTargetingOptions(createBrowserAssignedTargetingOptions); // Add browser assigned targeting options to list of create requests. createRequests.add(createBrowserTargetingRequest); // Set create requests in edit request. requestContent.setCreateRequests(createRequests); // Configure the bulk edit request. LineItems.BulkEditAssignedTargetingOptions request = service.advertisers().lineItems() .bulkEditAssignedTargetingOptions( advertiser-id, requestContent); // Execute bulk edit request. BulkEditAssignedTargetingOptionsResponse response = request.execute(); // Check if any line items updated successfully. if (response.getUpdatedLineItemIds() == null || response.getUpdatedLineItemIds().isEmpty()) { System.out.println("No line items were updated successfully."); } else { System.out.printf( "Targeting configurations for the following line item IDs were updated: %s.\n", Arrays.toString(response.getUpdatedLineItemIds().toArray())); } // Check if any line items failed to update. if (response.getFailedLineItemIds() == null || response.getFailedLineItemIds().isEmpty()) { System.out.println("No line items failed to update."); } else { // Print the line items that failed to update. System.out.printf( "Targeting configurations for the following line item IDs failed to update: %s.\n", Arrays.toString(response.getFailedLineItemIds().toArray())); // Print errors thrown for failed updates. System.out.println("The failed updates were caused by the following errors:"); for (Status error : response.getErrors()) { System.out.printf("Error Code: %s, Message: %s\n", error.getCode(), error.getMessage()); } }
Python
# Build assigned targeting option objects to create. createBrowserAssignedTargetingOptions = [] for targeting_id in create-browser-assigned-targeting-ids: createBrowserAssignedTargetingOptions.append( {'browserDetails': {'targetingOptionId': targeting_id}} ) # Create a bulk edit request. bulk_edit_line_item_request = { 'lineItemIds': line-item-ids, 'deleteRequests': [ { 'targetingType': 'TARGETING_TYPE_BROWSER', 'assignedTargetingOptionIds': delete-browser-assigned-targeting-ids }, { 'targetingType': 'TARGETING_TYPE_DEVICE_MAKE_MODEL', 'assignedTargetingOptionIds': delete-device-make-model-assigned-targeting-ids } ], 'createRequests': [ { 'targetingType': 'TARGETING_TYPE_BROWSER', 'assignedTargetingOptions': createBrowserAssignedTargetingOptions } ] } # Edit the line item targeting. response = service.advertisers().lineItems()\ .bulkEditAssignedTargetingOptions( advertiserId=advertiser-id, body=bulk_edit_line_item_request ).execute() # Print successfully updated line items. if 'updatedLineItemIds' not in response: print("No line items were updated successfully.") else: print("Targeting configurations for the following line item IDs were updated: %s" % response['updatedLineItemIds']) # Print line items that failed to update. if 'failedLineItemIds' not in response: print("No line items failed to update.") else: print("Targeting configurations for the following line item IDs failed to update: %s" % response['failedLineItemIds']) if 'errors' in response: print("The failed updates were caused by the following errors:") for error in response["errors"]: print("Error code: %s, Message: %s" % (error["code"], error["message"]))
PHP
// Create delete request list. $deleteRequests = array(); // Create and add browser assigned targeting option IDs to delete request list. $deleteBrowserTargetingRequest = new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest(); $deleteBrowserTargetingRequest->setTargetingType( "TARGETING_TYPE_BROWSER" ); $deleteBrowserTargetingRequest->setAssignedTargetingOptionIds( delete-browser-assigned-targeting-ids ); $deleteRequests[] = $deleteBrowserTargetingRequest; // Create and add device assigned targeting option IDs to delete request list. $deleteDeviceTargetingRequest = new Google_Service_DisplayVideo_DeleteAssignedTargetingOptionsRequest(); $deleteDeviceTargetingRequest->setTargetingType( "TARGETING_TYPE_DEVICE_MAKE_MODEL" ); $deleteDeviceTargetingRequest->setAssignedTargetingOptionIds( delete-device-make-model-assigned-targeting-ids ); $deleteRequests[] = $deleteDeviceTargetingRequest; // Create create request list. $createRequests = array(); // Create and populate list of browser assigned targetion options to create. $createBrowserAssignedTargetingOptions = array(); foreach (create-browser-assigned-targeting-ids as $optionId) { $option = new Google_Service_DisplayVideo_AssignedTargetingOption(); $details = new Google_Service_DisplayVideo_BrowserAssignedTargetingOptionDetails(); $details->setTargetingOptionId($optionId); $option->setBrowserDetails($details); $createBrowserAssignedTargetingOptions[] = $option; } // Create and add browser assigned targeting option create request to create // request list. $createBrowserTargetingRequest = new Google_Service_DisplayVideo_CreateAssignedTargetingOptionsRequest(); $createBrowserTargetingRequest->setTargetingType( "TARGETING_TYPE_BROWSER" ); $createBrowserTargetingRequest->setAssignedTargetingOptions( $createBrowserAssignedTargetingOptions ); $createRequests[] = $createBrowserTargetingRequest; // Create a bulk edit request and assign create and delete request lists. $body = new Google_Service_DisplayVideo_BulkEditAssignedTargetingOptionsRequest(); $body->setLineItemIds(line-item-ids); $body->setCreateRequests($createRequests); $body->setDeleteRequests($deleteRequests); // Call the API, editing the assigned targeting options for the identified // line item. $response = $service ->advertisers_lineItems ->bulkEditAssignedTargetingOptions( advertiser-id, $body ); // Print successfully updated line items. if (!empty($response->getUpdatedLineItemIds())) { printf('Targeting configurations for the following line item IDs were updated:\n'); foreach ($response->getUpdatedLineItemIds() as $id) { printf('%s\n', $id); } } else { print('No line items were updated successfully.\n'); } // Print line items that failed to update. if (!empty($response->getFailedLineItemIds())) { print('Targeting configurations for the following line item IDs failed to update:\n'); foreach ($response->getFailedLineItemIds() as $id) { printf('%s\n', $id); } print('The failed updates were caused by the following errors:\n'); foreach ($response->getErrors() as $error) { printf('Error Code: %s, Message: %s\n', $error->getCode(), $error->getMessage()); } } else { print('No line items failed to update.\n'); }