Method: sdfdownloadtasks.create

建立 SDF 下載工作。傳回 Operation

SDF 下載工作是長時間執行的非同步作業,這項作業的 metadata 類型為 SdfDownloadTaskMetadata。如果要求成功,作業的 response 類型就是 SdfDownloadTask。回應中不會包括必須使用 media.download 擷取的下載檔案。您可以使用 sdfdownloadtask.operations.get 擷取作業狀態。

您可以前往 error.message 查看所有錯誤。請注意,error.details 應為空白。

HTTP 要求

POST https://displayvideo.googleapis.com/v1/sdfdownloadtasks

這個網址使用 gRPC 轉碼語法。

要求主體

要求主體的資料會採用以下結構:

JSON 表示法
{
  "version": enum (SdfVersion),

  // Union field root_id can be only one of the following:
  "partnerId": string,
  "advertiserId": string
  // End of list of possible types for union field root_id.

  // Union field filtering_option can be only one of the following:
  "parentEntityFilter": {
    object (ParentEntityFilter)
  },
  "idFilter": {
    object (IdFilter)
  },
  "inventorySourceFilter": {
    object (InventorySourceFilter)
  }
  // End of list of possible types for union field filtering_option.
}
欄位
version

enum (SdfVersion)

必要欄位。下載檔案的 SDF 版本。如果設為 SDF_VERSION_UNSPECIFIED,系統預設會使用由 root_id 指定的廣告客戶或合作夥伴指定的版本。除非另有設定,否則廣告客戶會沿用夥伴的 SDF 版本。

聯集欄位 root_id。必要欄位。根 ID 決定下載要求的情境。只能設定一個欄位。root_id 只能是下列其中一項:
partnerId

string (int64 format)

要下載 SDF 的合作夥伴 ID。

advertiserId

string (int64 format)

要下載 SDF 的廣告客戶 ID。

聯集欄位 filtering_option。必要欄位。指定要下載的實體類型和範圍的選項。只能設定一個欄位。filtering_option 只能是下列其中一項:
parentEntityFilter

object (ParentEntityFilter)

所選檔案類型的篩選器。每個檔案中的實體都是根據一組所選的篩選器實體進行篩選。篩選器實體的類型必須與所選檔案類型的類型相同,或是父項類型的父項類型。

idFilter

object (IdFilter)

依實體 ID 篩選實體。

inventorySourceFilter

object (InventorySourceFilter)

按 ID 篩選廣告空間來源。

回應主體

如果成功,回應主體會包含新建立的 Operation 例項。

授權範圍

需要下列 OAuth 範圍:

  • https://www.googleapis.com/auth/display-video

詳情請參閱 OAuth 2.0 總覽

ParentEntityFilter

篩選選項,用於篩選屬於所選篩選器實體的所選檔案類型。

JSON 表示法
{
  "fileType": [
    enum (FileType)
  ],
  "filterType": enum (FilterType),
  "filterIds": [
    string
  ]
}
欄位
fileType[]

enum (FileType)

必要欄位。即將傳回的檔案類型。

filterType

enum (FilterType)

必要欄位。用於篩選已擷取實體的篩選器類型。

filterIds[]

string (int64 format)

指定篩選器類型的 ID。用於篩選要擷取的實體。如果篩選器類型並非「FILTER_TYPE_NONE」,則至少必須指定一個 ID。

FileType

可下載的檔案類型。

列舉
FILE_TYPE_UNSPECIFIED 未指定類型或此版本未知類型時的預設值。
FILE_TYPE_CAMPAIGN 廣告活動。
FILE_TYPE_MEDIA_PRODUCT 媒體產品。
FILE_TYPE_INSERTION_ORDER 廣告訂單。
FILE_TYPE_LINE_ITEM 委刊項。
FILE_TYPE_AD_GROUP YouTube 廣告群組。
FILE_TYPE_AD YouTube 廣告。

FilterType

可篩選的類型。

列舉
FILTER_TYPE_UNSPECIFIED 未指定類型或此版本未知類型時的預設值。
FILTER_TYPE_NONE 如果選取這個選項,下載內容就不會套用任何篩選器。只有在 CreateSdfDownloadTaskRequest 中指定了 Advertiser 時才能使用。
FILTER_TYPE_ADVERTISER_ID 廣告主 ID。如果選取,所有篩選器 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 Partner
FILTER_TYPE_CAMPAIGN_ID 廣告活動 ID。如果選取這個選項,所有篩選器 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner
FILTER_TYPE_MEDIA_PRODUCT_ID 媒體產品 ID。如果選取,所有篩選器 ID 都必須是屬於 CreateSdfDownloadTaskRequest 指定之 AdvertiserPartner 的「媒體產品 ID」。只能用於下載 FILE_TYPE_MEDIA_PRODUCT
FILTER_TYPE_INSERTION_ORDER_ID 廣告訂單 ID。如果選取這個選項,所有篩選器 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner。只能用於下載 FILE_TYPE_INSERTION_ORDERFILE_TYPE_LINE_ITEMFILE_TYPE_AD_GROUPFILE_TYPE_AD
FILTER_TYPE_LINE_ITEM_ID 委刊項 ID。如果選取這個選項,所有篩選器 ID 都必須是 CreateSdfDownloadTaskRequestPartner 中指定的 AdvertiserPartner 委刊項 ID。只能用於下載 FILE_TYPE_LINE_ITEMFILE_TYPE_AD_GROUPFILE_TYPE_AD

IdFilter

按照實體 ID 篩選實體的篩選選項。

JSON 表示法
{
  "campaignIds": [
    string
  ],
  "mediaProductIds": [
    string
  ],
  "insertionOrderIds": [
    string
  ],
  "lineItemIds": [
    string
  ],
  "adGroupIds": [
    string
  ],
  "adGroupAdIds": [
    string
  ]
}
欄位
campaignIds[]

string (int64 format)

要依 ID 下載的廣告活動。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

mediaProductIds[]

string (int64 format)

按 ID 下載的媒體產品。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

insertionOrderIds[]

string (int64 format)

要依 ID 下載的廣告訂單。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

lineItemIds[]

string (int64 format)

要依 ID 下載的委刊項。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

adGroupIds[]

string (int64 format)

依 ID 下載的 YouTube 廣告群組。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

adGroupAdIds[]

string (int64 format)

按 ID 下載的 YouTube 廣告。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner

InventorySourceFilter

用來篩選廣告空間來源實體的篩選選項。

JSON 表示法
{
  "inventorySourceIds": [
    string
  ]
}
欄位
inventorySourceIds[]

string (int64 format)

要依 ID 下載的廣告空間來源。所有 ID 都必須屬於 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner。留空即可下載所選廣告客戶或夥伴的所有廣告空間來源。