Method: sdfdownloadtasks.create

创建一项 SDF 下载任务。返回 Operation。

SDF 下载任务是一项长时间运行的异步操作。此操作的 metadata 类型为 SdfDownloadTaskMetadata。如果请求成功，则操作的 response 类型为 SdfDownloadTask。响应将不包含下载文件，必须使用 media.download 检索这些文件。

可以使用 sdfdownloadtasks.operations.get 检索操作状态。

任何错误都可以在 error.message 中找到。请注意，error.details 应为空。

HTTP 请求

POST https://displayvideo.googleapis.com/v4/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 Overview。

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 广告。
FILE_TYPE_LINE_ITEM_QA 订单项 - 质量检查格式。
FILE_TYPE_AD_GROUP_QA YouTube 广告组 - 质量检查格式。

FilterType

可以作为过滤条件的可能类型。

枚举
FILTER_TYPE_UNSPECIFIED 未指定类型或在此版本中类型未知时的默认值。
FILTER_TYPE_NONE 如果选中此复选框，系统不会对下载内容应用任何过滤条件。只有在 CreateSdfDownloadTaskRequest 中指定了 Advertiser 时才可使用。
FILTER_TYPE_ADVERTISER_ID 广告客户 ID。如果选中此项，所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 Partner 的广告客户 ID。
FILTER_TYPE_CAMPAIGN_ID 广告系列 ID。如果选中此项，所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 Advertiser 或 Partner 的广告系列 ID。
FILTER_TYPE_MEDIA_PRODUCT_ID 媒体产品 ID。如果选中此项，所有过滤器 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 Advertiser 或 Partner 的媒体产品 ID。只能用于下载 FILE_TYPE_MEDIA_PRODUCT。
FILTER_TYPE_INSERTION_ORDER_ID 广告订单 ID。如果选中此项，所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 Advertiser 或 Partner 的广告订单 ID。只能用于下载 FILE_TYPE_INSERTION_ORDER、FILE_TYPE_LINE_ITEM、FILE_TYPE_LINE_ITEM_QA、FILE_TYPE_AD_GROUP、FILE_TYPE_AD_GROUP_QA 和 FILE_TYPE_AD。
FILTER_TYPE_LINE_ITEM_ID 订单项 ID。如果选中此项，所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 Advertiser 或 Partner 的订单项 ID。只能用于下载 FILE_TYPE_LINE_ITEM、FILE_TYPE_LINE_ITEM_QA、FILE_TYPE_AD_GROUP、FILE_TYPE_AD_GROUP_QA 和 FILE_TYPE_AD。

IdFilter

按实体 ID 过滤实体的过滤选项。

JSON 表示法 
{
  "campaignIds": [
    string
  ],
  "mediaProductIds": [
    string
  ],
  "insertionOrderIds": [
    string
  ],
  "lineItemIds": [
    string
  ],
  "adGroupIds": [
    string
  ],
  "adGroupAdIds": [
    string
  ],
  "lineItemQaIds": [
    string
  ],
  "adGroupQaIds": [
    string
  ]
}
字段
campaignIds[]

string (int64 format)

要按 ID 下载的广告系列。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
mediaProductIds[]

string (int64 format)

要按 ID 下载的媒体产品。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
insertionOrderIds[]

string (int64 format)

要按 ID 下载的广告订单。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
lineItemIds[]

string (int64 format)

要按 ID 下载的订单项。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
adGroupIds[]

string (int64 format)

要按 ID 下载的 YouTube 广告组。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
adGroupAdIds[]

string (int64 format)

根据 ID 下载的 YouTube 广告。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
lineItemQaIds[]

string (int64 format)

可选。按 ID 划分的订单项，以质量检查格式下载。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。
adGroupQaIds[]

string (int64 format)

可选。按 ID 细分的 YouTube 广告组，以质量检查格式下载。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。

InventorySourceFilter

用于根据广告资源来源实体进行过滤的过滤选项。

JSON 表示法 
{
  "inventorySourceIds": [
    string
  ]
}
字段
inventorySourceIds[]

string (int64 format)

要按 ID 下载的广告资源来源。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 Advertiser 或 Partner。留空可下载所选广告客户或合作伙伴的所有广告资源来源。