Method: sdfdownloadtasks.create

  • The sdfdownloadtasks.create method creates a long-running operation to download Structured Data Files (SDF).

  • The request body requires specifying the SDF version, either a partner or advertiser ID as the root, and a filtering option using ParentEntityFilter, IdFilter, or InventorySourceFilter.

  • File types and filter types can be specified to narrow down the downloaded entities.

  • The response is an Operation object; the actual download files must be retrieved separately using media.download.

  • This method requires the https://www.googleapis.com/auth/display-video OAuth scope for authorization.

Creates an SDF Download Task. Returns an Operation.

An SDF Download Task is a long-running, asynchronous operation. The metadata type of this operation is SdfDownloadTaskMetadata. If the request is successful, the response type of the operation is SdfDownloadTask. The response will not include the download files, which must be retrieved with media.download.

The state of operation can be retrieved with sdfdownloadtasks.operations.get.

Any errors can be found in the error.message. Note that error.details is expected to be empty.

HTTP request

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

The URL uses gRPC Transcoding syntax.

Request body

The request body contains data with the following structure:

JSON representation 
{
  "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.
}
Fields
version

enum (SdfVersion)

Required. The SDF version of the downloaded file. If set to SDF_VERSION_UNSPECIFIED, this will default to the version specified by the advertiser or partner identified by root_id. An advertiser inherits its SDF version from its partner unless configured otherwise.
Union field root_id. Required. The root ID determines the context of the download request. Exactly one field must be set. root_id can be only one of the following:
partnerId

string (int64 format)

The ID of the partner to download SDF for.
advertiserId

string (int64 format)

The ID of the advertiser to download SDF for.
Union field filtering_option. Required. Options that specify the entity types and ranges to download. Exactly one field must be set. filtering_option can be only one of the following:
parentEntityFilter

object (ParentEntityFilter)

Filters on selected file types. The entities in each file are filtered by a chosen set of filter entities. The filter entities must be the same type as, or a parent type of, the selected file types.
idFilter

object (IdFilter)

Filters on entities by their entity IDs.
inventorySourceFilter

object (InventorySourceFilter)

Filters on Inventory Sources by their IDs.

Response body

If successful, the response body contains a newly created instance of Operation.

Authorization scopes

Requires the following OAuth scope:

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

For more information, see the OAuth 2.0 Overview.

ParentEntityFilter

A filtering option that filters on selected file types belonging to a chosen set of filter entities.

JSON representation 
{
  "fileType": [
    enum (FileType)
  ],
  "filterType": enum (FilterType),
  "filterIds": [
    string
  ]
}
Fields
fileType[]

enum (FileType)

Required. File types that will be returned.
filterType

enum (FilterType)

Required. Filter type used to filter fetched entities.
filterIds[]

string (int64 format)

The IDs of the specified filter type. This is used to filter entities to fetch. If filter type is not FILTER_TYPE_NONE, at least one ID must be specified.

FileType

Possible types of files that can be downloaded.

Enums
FILE_TYPE_UNSPECIFIED Default value when type is unspecified or is unknown in this version.
FILE_TYPE_CAMPAIGN Campaign.
FILE_TYPE_MEDIA_PRODUCT Media Product.
FILE_TYPE_INSERTION_ORDER Insertion Order.
FILE_TYPE_LINE_ITEM Line Item.
FILE_TYPE_AD_GROUP YouTube Ad Group.
FILE_TYPE_AD YouTube Ad.
FILE_TYPE_LINE_ITEM_QA Line Item - QA format.
FILE_TYPE_AD_GROUP_QA YouTube Ad Group - QA format.

FilterType

Possible types that can be filtered on.

Enums
FILTER_TYPE_UNSPECIFIED Default value when type is unspecified or is unknown in this version.
FILTER_TYPE_NONE If selected, no filter will be applied to the download. Can only be used if an Advertiser is specified in CreateSdfDownloadTaskRequest.
FILTER_TYPE_ADVERTISER_ID Advertiser ID. If selected, all filter IDs must be Advertiser IDs that belong to the Partner specified in CreateSdfDownloadTaskRequest.
FILTER_TYPE_CAMPAIGN_ID Campaign ID. If selected, all filter IDs must be Campaign IDs that belong to the Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
FILTER_TYPE_MEDIA_PRODUCT_ID Media Product ID. If selected, all filter IDs must be Media Product IDs that belong to the Advertiser or Partner specified in CreateSdfDownloadTaskRequest. Can only be used for downloading FILE_TYPE_MEDIA_PRODUCT.
FILTER_TYPE_INSERTION_ORDER_ID Insertion Order ID. If selected, all filter IDs must be Insertion Order IDs that belong to the Advertiser or Partner specified in CreateSdfDownloadTaskRequest. Can only be used for downloading FILE_TYPE_INSERTION_ORDER, FILE_TYPE_LINE_ITEM, FILE_TYPE_LINE_ITEM_QA, FILE_TYPE_AD_GROUP, FILE_TYPE_AD_GROUP_QA, and FILE_TYPE_AD.
FILTER_TYPE_LINE_ITEM_ID Line Item ID. If selected, all filter IDs must be Line Item IDs that belong to the Advertiser or Partner specified in CreateSdfDownloadTaskRequest. Can only be used for downloading FILE_TYPE_LINE_ITEM, FILE_TYPE_LINE_ITEM_QA,FILE_TYPE_AD_GROUP, FILE_TYPE_AD_GROUP_QA, and FILE_TYPE_AD.

IdFilter

A filtering option that filters entities by their entity IDs.

JSON representation 
{
  "campaignIds": [
    string
  ],
  "mediaProductIds": [
    string
  ],
  "insertionOrderIds": [
    string
  ],
  "lineItemIds": [
    string
  ],
  "adGroupIds": [
    string
  ],
  "adGroupAdIds": [
    string
  ],
  "lineItemQaIds": [
    string
  ],
  "adGroupQaIds": [
    string
  ]
}
Fields
campaignIds[]

string (int64 format)

Campaigns to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
mediaProductIds[]

string (int64 format)

Media Products to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
insertionOrderIds[]

string (int64 format)

Insertion Orders to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
lineItemIds[]

string (int64 format)

Line Items to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
adGroupIds[]

string (int64 format)

YouTube Ad Groups to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
adGroupAdIds[]

string (int64 format)

YouTube Ads to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
lineItemQaIds[]

string (int64 format)

Optional. Line Items, by ID, to download in QA format. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.
adGroupQaIds[]

string (int64 format)

Optional. YouTube Ad Groups, by ID, to download in QA format. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest.

InventorySourceFilter

A filtering option for filtering on Inventory Source entities.

JSON representation 
{
  "inventorySourceIds": [
    string
  ]
}
Fields
inventorySourceIds[]

string (int64 format)

Inventory Sources to download by ID. All IDs must belong to the same Advertiser or Partner specified in CreateSdfDownloadTaskRequest. Leave empty to download all Inventory Sources for the selected Advertiser or Partner.