資源指定功能是 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
advertisers.lineItems.bulkUpdate
advertisers.lineItems.patch
advertisers.lineItems.targetingTypes.assignedTargetingOptions.create
advertisers.lineItems.targetingTypes.assignedTargetingOptions.delete
如果您需要同時為單一委刊項新增或移除多個指派的指定目標選項,請使用單一 advertisers.lineItems.bulkEditAssignedTargetingOptions
要求。如要更新委刊項的設定和指定目標,請將 patch
或 bulkUpdate
要求和相關指定目標要求排入佇列,以確保在第一個傳回回應之前,系統不會傳送第二個請求。