本指南介绍如何使用 Display & Video 360 API advertisers.assets 和 advertisers.creatives 服务上传广告素材资源和构建 Display & Video 360 Creative 资源。
前提条件
在使用 Display & Video 360 API 制作广告素材之前，请先完成以下步骤。
确保您的 Display & Video 360 用户个人资料（由用户或服务帐号电子邮件地址标识）对相应广告客户具有读取和写入权限。如果您没有读取和写入权限，请与团队中现有的管理员用户联系。
制作新的广告素材
通过 Display & Video 360 API 使用新素材资源制作新广告素材至少需要两个 API 请求。第一个用于上传广告素材资源，第二个用于构建广告素材对象。
上传素材资源
如需将必要的广告素材 assets 上传到 Display & Video 360，请调用 advertisers.assets.upload 方法。
必须将素材资源分配给与广告素材相同的广告客户。
在您上传资源后，该 API 会返回一个包含 asset 对象的响应。您以后将无法再检索此 asset 对象，因此请记下相应的 mediaId。此素材资源的 mediaId 用于将该素材资源分配给广告素材。
特定广告素材类型仅接受特定文件类型作为特定素材资源角色中的素材资源。如需详细了解如何为您的广告素材选择合适的文件类型，请参阅帮助中心。
以下示例说明了如何上传素材资源：
Java
// Create the asset upload request content.
CreateAssetRequest content = new CreateAssetRequest();
content.setFilename(asset-filename);
// Create input stream for the creative asset.
InputStreamContent assetStream = new InputStreamContent(
getMimeType(asset-filename),
new FileInputStream(asset-path));
// Configure the asset upload request.
Assets.Upload assetRequest = service.advertisers().assets()
.upload(advertiser-id, content, assetStream);
// Upload the asset.
CreateAssetResponse assetResponse = assetRequest.execute();
// Display the new asset media ID.
Asset asset = assetResponse.getAsset();
System.out.printf("The asset has been upload with media ID %s",
asset.getMediaId());
此示例使用以下辅助函数查找文件 MIME 类型：
import java.net.FileNameMap;
import java.net.URLConnection;
private static String getMimeType(String fileName) {
// Parse filename for appropriate MIME type.
FileNameMap fileNameMap = URLConnection.getFileNameMap();
String mimeType = fileNameMap.getContentTypeFor(fileName);
// If MIME type was found, return it.
if (mimeType != null) {
return mimeType;
}
// Otherwise, return a default value.
return "application/octet-stream";
}
Python
# Create the request body.
body = {
'filename': asset-filename
}
# Create upload object.
media = MediaFileUpload(asset-path)
if not media.mimetype():
media = MediaFileUpload(asset-path, 'application/octet-stream')
# Upload the asset.
response = service.advertisers().assets().upload(
advertiserId=advertiser-id,
body=body,
media_body=media
).execute()
# Display the new asset media ID.
print("Asset was created with media ID %s." % response['asset']['mediaId'])
PHP
$body = new Google_Service_DisplayVideo_CreateAssetRequest();
$body->setFilename(asset-filename);
$optParams = array(
'data' => file_get_contents(asset-path),
'mimeType' => mime_content_type(asset-filename),
'uploadType' => 'media'
);
// Call the API, uploading the asset file to Display & Video 360.
$result = $service->advertisers_assets->upload(
advertiser-id,
$body,
$optParams
);
// Display the new asset media ID.
printf(
'Asset was created with media ID %s.',
$result->getAsset()->getMediaId()
);
cURL
curl --request POST \
'https://displayvideo.googleapis.com/upload/v3/advertisers/advertiser-id/assets?uploadType=multipart'
--header 'Authorization: Bearer access-token' \
-F "data={\"filename\": \"asset-filename\"};type=application/json;charset=UTF-8" \
-F "file=@asset-path;type=asset-mime-type"
制作广告素材
上传素材资源并获取其媒体 ID 后，您可以使用这些素材资源构建完整的 Creative 对象。
使用 advertisers.creatives.create 方法创建新的 Creative。每种广告素材类型只需要一部分 Creative 字段。
请参阅本指南的附录，详细了解如何将界面字段映射到每种广告素材类型的相应 API 字段。
以下示例说明了如何制作原生展示广告素材、HTML5 广告素材和视频广告素材：
原生展示广告
Java
// Create a creative object.
Creative creative = new Creative();
creative.setDisplayName(display-name);
creative.setEntityStatus("ENTITY_STATUS_ACTIVE");
creative.setHostingSource("HOSTING_SOURCE_HOSTED");
// Set native creative type.
creative.setCreativeType("CREATIVE_TYPE_NATIVE");
// Create a dimensions object.
Dimensions dimensions = new Dimensions();
dimensions.setHeightPixels(creative-height-pixels);
dimensions.setWidthPixels(creative-width-pixels);
// Add the dimensions object to the creative object.
creative.setDimensions(dimensions);
// Create list for asset associations.
List<AssetAssociation> assetAssociations = new ArrayList<AssetAssociation>();
// Assign the image asset to a role.
AssetAssociation mainImageAssetAssociation = new AssetAssociation();
mainImageAssetAssociation.setAsset(new Asset().setMediaId(image-asset-media-id));
mainImageAssetAssociation.setRole("ASSET_ROLE_MAIN");
assetAssociations.add(mainImageAssetAssociation);
// Assign the logo asset to a role.
AssetAssociation iconAssetAssociation = new AssetAssociation();
iconAssetAssociation.setAsset(new Asset().setMediaId(logo-asset-media-id));
iconAssetAssociation.setRole("ASSET_ROLE_ICON");
assetAssociations.add(iconAssetAssociation);
// Create and assign advertiser name asset.
Asset advertiserNameAsset = new Asset();
advertiserNameAsset.setContent(advertiser-name);
AssetAssociation advertiserNameAssetAssociation = new AssetAssociation();
advertiserNameAssetAssociation.setAsset(advertiserNameAsset);
advertiserNameAssetAssociation.setRole("ASSET_ROLE_ADVERTISER_NAME");
assetAssociations.add(advertiserNameAssetAssociation);
// Create and assign headline asset.
Asset headlineAsset = new Asset();
headlineAsset.setContent(headline);
AssetAssociation headlineAssetAssociation = new AssetAssociation();
headlineAssetAssociation.setAsset(headlineAsset);
headlineAssetAssociation.setRole("ASSET_ROLE_HEADLINE");
assetAssociations.add(headlineAssetAssociation);
// Create and assign body text asset.
Asset bodyTextAsset = new Asset();
bodyTextAsset.setContent(body-text);
AssetAssociation bodyTextAssetAssociation = new AssetAssociation();
bodyTextAssetAssociation.setAsset(bodyTextAsset);
bodyTextAssetAssociation.setRole("ASSET_ROLE_BODY");
assetAssociations.add(bodyTextAssetAssociation);
// Create and assign caption URL asset.
Asset captionUrlAsset = new Asset();
captionUrlAsset.setContent(caption-url);
AssetAssociation captionUrlAssetAssociation = new AssetAssociation();
captionUrlAssetAssociation.setAsset(captionUrlAsset);
captionUrlAssetAssociation.setRole("ASSET_ROLE_CAPTION_URL");
assetAssociations.add(captionUrlAssetAssociation);
// Create and assign call to action asset.
Asset callToActionAsset = new Asset();
callToActionAsset.setContent(call-to-action);
AssetAssociation callToActionAssetAssociation = new AssetAssociation();
callToActionAssetAssociation.setAsset(callToActionAsset);
callToActionAssetAssociation.setRole("ASSET_ROLE_CALL_TO_ACTION");
assetAssociations.add(callToActionAssetAssociation);
// Create and set the list of creative assets.
creative.setAssets(assetAssociations);
// Create an exit event.
ExitEvent exitEvent = new ExitEvent();
exitEvent.setType("EXIT_EVENT_TYPE_DEFAULT");
exitEvent.setUrl(landing-page-url);
// Create and set the list of exit events for the creative.
creative.setExitEvents(ImmutableList.of(exitEvent));
// Configure the create request.
Creatives.Create request =
service.advertisers().creatives().create(advertiser-id, creative);
// Send the request.
Creative response = request.execute();
// Display the new creative.
System.out.printf(
"Creative %s was created.\n",
response.getName());
Python
# Create a creative object.
creative_obj = {
'displayName': display-name,
'entityStatus': 'ENTITY_STATUS_ACTIVE',
'hostingSource': 'HOSTING_SOURCE_HOSTED',
'creativeType': 'CREATIVE_TYPE_NATIVE',
'dimensions': {
'heightPixels': creative-height-pixels,
'widthPixels': creative-width-pixels
},
'assets': [
{
'asset': {'mediaId' : image-asset-media-id},
'role': 'ASSET_ROLE_MAIN'
},
{
'asset': {'mediaId' : logo-asset-media-id},
'role': 'ASSET_ROLE_ICON'
},
{
'asset': {'content' : advertiser-name},
'role': 'ASSET_ROLE_ADVERTISER_NAME'
},
{
'asset': {'content' : headline},
'role': 'ASSET_ROLE_HEADLINE'
},
{
'asset': {'content' : body-text},
'role': 'ASSET_ROLE_BODY'
},
{
'asset': {'content' : caption-url},
'role': 'ASSET_ROLE_CAPTION_URL'
},
{
'asset': {'content' : call-to-action},
'role': 'ASSET_ROLE_CALL_TO_ACTION'
},
],
'exitEvents': [
{
'type': 'EXIT_EVENT_TYPE_DEFAULT',
'url': landing-page-url
}
]
}
# Create the creative.
creative = service.advertisers().creatives().create(
advertiserId=advertiser-id,
body=creative_obj
).execute()
# Display the new creative.
print("creative %s was created." % creative["name"])
PHP
// Create a creative object.
$creative = new Google_Service_DisplayVideo_Creative();
$creative->setDisplayName(display-name);
$creative->setEntityStatus('ENTITY_STATUS_ACTIVE');
$creative->setHostingSource('HOSTING_SOURCE_HOSTED');
// Set native creative type.
$creative->setCreativeType('CREATIVE_TYPE_NATIVE');
// Create a dimensions object.
$dimensions = new Google_Service_DisplayVideo_Dimensions();
$dimensions->setHeightPixels(creative-height-pixels);
$dimensions->setWidthPixels(creative-width-pixels);
// Add the dimensions object to the creative object.
$creative->setDimensions($dimensions);
// Create list for asset associations.
$assetAssociations = array();
// Assign the image asset to a role.
$imageAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$imageAsset = new Google_Service_DisplayVideo_Asset();
$imageAsset->setMediaId(image-asset-media-id);
$imageAssetAssoc->setAsset($imageAsset);
$imageAssetAssoc->setRole('ASSET_ROLE_MAIN');
$assetAssociations[] = $imageAssetAssoc;
// Assign the logo asset to a role.
$iconAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$iconAsset = new Google_Service_DisplayVideo_Asset();
$iconAsset->setMediaId(logo-asset-media-id);
$iconAssetAssoc->setAsset($iconAsset);
$iconAssetAssoc->setRole('ASSET_ROLE_ICON');
$assetAssociations[] = $iconAssetAssoc;
// Create and assign advertiser name asset.
$advNameAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$advNameAsset = new Google_Service_DisplayVideo_Asset();
$advNameAsset->setContent(advertiser-name);
$advNameAssetAssoc->setAsset($advNameAsset);
$advNameAssetAssoc->setRole('ASSET_ROLE_ADVERTISER_NAME');
$assetAssociations[] = $advNameAssetAssoc;
// Create and assign headline asset.
$headlineAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$headlineAsset = new Google_Service_DisplayVideo_Asset();
$headlineAsset->setContent(headline);
$headlineAssetAssoc->setAsset($headlineAsset);
$headlineAssetAssoc->setRole('ASSET_ROLE_HEADLINE');
$assetAssociations[] = $headlineAssetAssoc;
// Create and assign body text asset.
$bodyTextAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$bodyTextAsset = new Google_Service_DisplayVideo_Asset();
$bodyTextAsset->setContent(body-text);
$bodyTextAssetAssoc->setAsset($bodyTextAsset);
$bodyTextAssetAssoc->setRole('ASSET_ROLE_BODY');
$assetAssociations[] = $bodyTextAssetAssoc;
// Create and assign caption URL asset.
$captionUrlAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$captionUrlAsset = new Google_Service_DisplayVideo_Asset();
$captionUrlAsset->setContent(caption-url);
$captionUrlAssetAssoc->setAsset($captionUrlAsset);
$captionUrlAssetAssoc->setRole('ASSET_ROLE_CAPTION_URL');
$assetAssociations[] = $captionUrlAssetAssoc;
// Create and assign call to action asset.
$cToAAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$cToAAsset = new Google_Service_DisplayVideo_Asset();
$cToAAsset->setContent(call-to-action);
$cToAAssetAssoc->setAsset($cToAAsset);
$cToAAssetAssoc->setRole('ASSET_ROLE_CALL_TO_ACTION');
$assetAssociations[] = $cToAAssetAssoc;
// Set the list of creative assets.
$creative->setAssets($assetAssociations);
// Create an exit event.
$exitEvent = new Google_Service_DisplayVideo_ExitEvent();
$exitEvent->setType('EXIT_EVENT_TYPE_DEFAULT');
$exitEvent->setUrl(landing-page-url);
// Create and set the list of exit events for the creative.
$creative->setExitEvents(array($exitEvent));
// Send the create request.
$result = $this->service->advertisers_creatives->create(
advertiser-id,
$creative
);
printf('Creative %s was created.', $result['name']);
HTML5
Java
// Create a creative object.
Creative creative = new Creative();
creative.setDisplayName(display-name);
creative.setEntityStatus("ENTITY_STATUS_ACTIVE");
creative.setHostingSource("HOSTING_SOURCE_HOSTED");
// Set standard creative type.
creative.setCreativeType("CREATIVE_TYPE_STANDARD");
// Create a dimensions object.
Dimensions dimensions = new Dimensions();
dimensions.setHeightPixels(creative-height-pixels);
dimensions.setWidthPixels(creative-width-pixels);
// Add the dimensions object to the creative object.
creative.setDimensions(dimensions);
// Assign the HTML5 asset to a role.
AssetAssociation assetAssociation = new AssetAssociation();
assetAssociation.setAsset(new Asset().setMediaId(html5-asset-media-id));
assetAssociation.setRole("ASSET_ROLE_MAIN");
// Create and set the list of creative assets.
creative.setAssets(ImmutableList.of(assetAssociation));
// Create an exit event.
ExitEvent exitEvent = new ExitEvent();
exitEvent.setName(exit-event-name);
exitEvent.setType("EXIT_EVENT_TYPE_DEFAULT");
exitEvent.setUrl(exit-event-url);
// Create and set the list of exit events for the creative.
creative.setExitEvents(ImmutableList.of(exitEvent));
// Configure the create request.
Creatives.Create request =
service.advertisers().creatives().create(advertiser-id, creative);
// Send the request.
Creative response = request.execute();
// Display the new creative.
System.out.printf(
"Creative %s was created.\n",
response.getName());
Python
# Create a creative object.
creative_obj = {
'displayName': display-name,
'entityStatus': 'ENTITY_STATUS_ACTIVE',
'hostingSource': 'HOSTING_SOURCE_HOSTED',
'creativeType': 'CREATIVE_TYPE_STANDARD',
'dimensions': {
'heightPixels': creative-height-pixels,
'widthPixels': creative-width-pixels
},
'assets': [
{
'asset': {'mediaId' : html5-asset-media-id},
'role': 'ASSET_ROLE_MAIN'
}
],
'exitEvents': [
{
'name': exit-event-name,
'type': 'EXIT_EVENT_TYPE_DEFAULT',
'url': exit-event-url
}
]
}
# Create the creative.
creative = service.advertisers().creatives().create(
advertiserId=advertiser-id,
body=creative_obj
).execute()
# Display the new creative.
print("Creative %s was created." % creative["name"])
PHP
// Create a creative object.
$creative = new Google_Service_DisplayVideo_Creative();
$creative->setDisplayName(display-name);
$creative->setEntityStatus('ENTITY_STATUS_ACTIVE');
$creative->setHostingSource('HOSTING_SOURCE_HOSTED');
// Set standard creative type.
$creative->setCreativeType('CREATIVE_TYPE_STANDARD');
// Create a dimensions object.
$dimensions = new Google_Service_DisplayVideo_Dimensions();
$dimensions->setHeightPixels(creative-height-pixels);
$dimensions->setWidthPixels(creative-width-pixels);
// Add the dimensions object to the creative object.
$creative->setDimensions($dimensions);
// Assign the HTML asset to a role.
$htmlAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$htmlAsset = new Google_Service_DisplayVideo_Asset();
$htmlAsset->setMediaId(html5-asset-media-id);
$htmlAssetAssoc->setAsset($htmlAsset);
$htmlAssetAssoc->setRole('ASSET_ROLE_MAIN');
// Create and set the list of creative assets.
$creative->setAssets(array($htmlAssetAssoc));
// Create an exit event.
$exitEvent = new Google_Service_DisplayVideo_ExitEvent();
$exitEvent->setName(exit-event-name);
$exitEvent->setType('EXIT_EVENT_TYPE_DEFAULT');
$exitEvent->setUrl(exit-event-url);
// Create and set the list of exit events for the creative.
$creative->setExitEvents(array($exitEvent));
// Send the create request.
$result = $this->service->advertisers_creatives->create(
advertiser-id,
$creative
);
printf('Creative %s was created.', $result['name']);
视频
Java
// Create a creative object.
Creative creative = new Creative();
creative.setDisplayName(display-name);
creative.setEntityStatus("ENTITY_STATUS_ACTIVE");
creative.setHostingSource("HOSTING_SOURCE_HOSTED");
// Set video creative type.
creative.setCreativeType("CREATIVE_TYPE_VIDEO");
// Assign the video asset to a role.
AssetAssociation assetAssociation = new AssetAssociation();
assetAssociation.setAsset(new Asset().setMediaId(video-asset-media-id));
assetAssociation.setRole("ASSET_ROLE_MAIN");
// Create and set the list of creative assets.
creative.setAssets(ImmutableList.of(assetAssociation));
// Create an exit event.
ExitEvent exitEvent = new ExitEvent();
exitEvent.setName(exit-event-name);
exitEvent.setType("EXIT_EVENT_TYPE_DEFAULT");
exitEvent.setUrl(exit-event-url);
// Create and set the list of exit events for the creative.
creative.setExitEvents(ImmutableList.of(exitEvent));
// Configure the create request.
Creatives.Create request =
service.advertisers().creatives().create(advertiser-id, creative);
// Send the request.
Creative response = request.execute();
// Display the new creative.
System.out.printf(
"Creative %s was created.\n",
response.getName());
Python
# Create a creative object.
creative_obj = {
'displayName': display-name,
'entityStatus': 'ENTITY_STATUS_ACTIVE',
'hostingSource': 'HOSTING_SOURCE_HOSTED',
'creativeType': 'CREATIVE_TYPE_VIDEO',
'assets': [
{
'asset': {'mediaId' : video-asset-media-id},
'role': 'ASSET_ROLE_MAIN'
}
],
'exitEvents': [
{
'name': exit-event-name,
'type': 'EXIT_EVENT_TYPE_DEFAULT',
'url': exit-event-url
}
]
}
# Create the creative.
creative = service.advertisers().creatives().create(
advertiserId=advertiser-id,
body=creative_obj
).execute()
# Display the new creative.
print("creative %s was created." % creative["name"])
PHP
// Create a creative object.
$creative = new Google_Service_DisplayVideo_Creative();
$creative->setDisplayName(display-name);
$creative->setEntityStatus('ENTITY_STATUS_ACTIVE');
$creative->setHostingSource('HOSTING_SOURCE_HOSTED');
// Set video creative type.
$creative->setCreativeType('CREATIVE_TYPE_VIDEO');
// Assign the video asset to a role.
$videoAssetAssoc = new Google_Service_DisplayVideo_AssetAssociation();
$videoAsset = new Google_Service_DisplayVideo_Asset();
$videoAsset->setMediaId(video-asset-media-id);
$videoAssetAssoc->setAsset($videoAsset);
$videoAssetAssoc->setRole('ASSET_ROLE_MAIN');
// Create and set the list of creative assets.
$creative->setAssets(array($videoAssetAssoc));
// Create an exit event.
$exitEvent = new Google_Service_DisplayVideo_ExitEvent();
$exitEvent->setName(exit-event-name);
$exitEvent->setType('EXIT_EVENT_TYPE_DEFAULT');
$exitEvent->setUrl(exit-event-url);
// Create and set the list of exit events for the creative.
$creative->setExitEvents(array($exitEvent));
// Send the create request.
$result = $this->service->advertisers_creatives->create(
advertiser-id,
$creative
);
printf('Creative %s was created.', $result['name']);