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/v3/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 广告。
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 中指定的 AdvertiserPartner 的广告系列 ID。
FILTER_TYPE_MEDIA_PRODUCT_ID 媒体产品 ID。如果选中此项,所有过滤器 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner 的媒体产品 ID。只能用于下载 FILE_TYPE_MEDIA_PRODUCT
FILTER_TYPE_INSERTION_ORDER_ID 广告订单 ID。如果选中此项,所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner 的广告订单 ID。只能用于下载 FILE_TYPE_INSERTION_ORDERFILE_TYPE_LINE_ITEMFILE_TYPE_LINE_ITEM_QAFILE_TYPE_AD_GROUPFILE_TYPE_AD_GROUP_QAFILE_TYPE_AD
FILTER_TYPE_LINE_ITEM_ID 订单项 ID。如果选中此项,所有过滤条件 ID 都必须是属于 CreateSdfDownloadTaskRequest 中指定的 AdvertiserPartner 的订单项 ID。只能用于下载 FILE_TYPE_LINE_ITEMFILE_TYPE_LINE_ITEM_QAFILE_TYPE_AD_GROUPFILE_TYPE_AD_GROUP_QAFILE_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 中指定的同一 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

lineItemQaIds[]

string (int64 format)

可选。按 ID 划分的订单项,以质量检查格式下载。所有 ID 都必须属于 CreateSdfDownloadTaskRequest 中指定的同一 AdvertiserPartner

adGroupQaIds[]

string (int64 format)

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

InventorySourceFilter

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

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

string (int64 format)

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