常見廣告投放工作

本頁將說明如何使用 DCM/DFA Reporting and Trafficking API 執行一些最常見的廣告投放工作。

一般程式設計秘訣

• 必要和選用屬性和參數 - 請參閱參考說明文件，瞭解 API 呼叫是否需要屬性或參數。
• 萬用字元名稱搜尋：您可以在搜尋物件名稱時，使用星號 (*) 萬用字元。星號可比對零個或多個任何字元。本 API 也支援隱含的子字串搜尋，因此搜尋「abc」將間接搜尋「*abc*」。
• 更新與修補：如要修改現有物件，有兩種方法可供選擇：
  1. 更新 - 更新物件時，系統會在插入物件時覆寫所有欄位。請務必載入您想要更新的物件，並對該物件進行任何變更。否則，凡是更新要求中沒有的欄位，都會遭到設定。
  2. 修補 - 修補時，只有指定欄位會在插入時覆寫。在此情況下，您可以建立新物件、為其指派要更新物件的 ID、設定要更新的欄位，以及執行修補要求。
• 大小：實體尺寸會以大小服務定義的 Size 物件表示。帳戶提供一組標準尺寸，您可以在這份清單中新增自訂大小。
• 日期和時間：您可以使用當地時區以 RFC 3339 格式儲存日期/時間；API 傳回的所有值都採用世界標準時間。這與顯示日期和時間的網站不同，後者是你設定的時區 (預設為美國/紐約時間)。

建立廣告客戶

C#

1. 建立 Advertiser 物件，並設定必要的 name 和 status 屬性。

   // Create the advertiser structure.
   Advertiser advertiser = new Advertiser();
   advertiser.Name = advertiserName;
   advertiser.Status = "APPROVED";
   

2. 呼叫 advertisers.insert() 儲存廣告客戶。

   // Create the advertiser.
   Advertiser result = service.Advertisers.Insert(advertiser, profileId).Execute();
   

Java

1. 建立 Advertiser 物件，並設定必要的 name 和 status 屬性。

   // Create the advertiser structure.
   Advertiser advertiser = new Advertiser();
   advertiser.setName(advertiserName);
   advertiser.setStatus("APPROVED");
   

2. 呼叫 advertisers.insert() 儲存廣告客戶。

   // Create the advertiser.
   Advertiser result = reporting.advertisers().insert(profileId, advertiser).execute();
   

PHP

1. 建立 Advertiser 物件，並設定必要的 name 和 status 屬性。

   $advertiser = new Google_Service_Dfareporting_Advertiser();
   $advertiser->setName($values['advertiser_name']);
   $advertiser->setStatus('APPROVED');
   

2. 呼叫 advertisers.insert() 儲存廣告客戶。

   $result = $this->service->advertisers->insert(
       $values['user_profile_id'],
       $advertiser
   );
   

Python

1. 建立 Advertiser 物件，並設定必要的 name 和 status 屬性。

   # Construct and save advertiser.
   advertiser = {
       'name': 'Test Advertiser',
       'status': 'APPROVED'
   }
   

2. 呼叫 advertisers.insert() 儲存廣告客戶。

   request = service.advertisers().insert(
       profileId=profile_id, body=advertiser)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 建立 Advertiser 物件，並設定必要的 name 和 status 屬性。

   # Create a new advertiser resource to insert.
   advertiser = DfareportingUtils::API_NAMESPACE::Advertiser.new(
     name: format('Example Advertiser #%s', SecureRandom.hex(3)),
     status: 'APPROVED'
   )
   

2. 呼叫 advertisers.insert() 儲存廣告客戶。

   # Insert the advertiser.
   result = service.insert_advertiser(profile_id, advertiser)
   

建立廣告活動

C#

1. 建立 Campaign 物件並設定必要屬性：

   • advertiserId：與這個廣告活動建立關聯的廣告客戶。
   • name - 這個廣告主的所有廣告活動皆不得重複。
   • defaultLandingPageId：如果使用者點按這個廣告活動中的廣告，系統會將他們導向的到達網頁。您可以呼叫 advertiserLandingPages.list 來查詢現有到達網頁，或是呼叫 advertiserLandingPages.insert 來建立新到達網頁。
   • 開始和結束日期 - 這些日期必須是未來的時間，而且可以精準反映日期。詳情請參閱一般編碼資訊中的日期和時間項目符號。個別廣告日期可以超過結束日期，方便發布商在指定的廣告活動結束日期內履行指定動作合約。

   // Locate an advertiser landing page to use as a default.
   LandingPage defaultLandingPage = getAdvertiserLandingPage(service, profileId, advertiserId);
   
   // Create the campaign structure.
   Campaign campaign = new Campaign();
   campaign.Name = campaignName;
   campaign.AdvertiserId = advertiserId;
   campaign.Archived = false;
   campaign.DefaultLandingPageId = defaultLandingPage.Id;
   
   // Set the campaign start date. This example uses today's date.
   campaign.StartDate =
       DfaReportingDateConverterUtil.convertToDateString(DateTime.Now);
   
   // Set the campaign end date. This example uses one month from today's date.
   campaign.EndDate =
       DfaReportingDateConverterUtil.convertToDateString(DateTime.Now.AddMonths(1));
   

2. 呼叫 campaigns.insert() 儲存廣告活動。

   // Insert the campaign.
   Campaign result = service.Campaigns.Insert(campaign, profileId).Execute();
   

Java

1. 建立 Campaign 物件並設定必要屬性：

   • advertiserId：與這個廣告活動建立關聯的廣告客戶。
   • name - 這個廣告主的所有廣告活動皆不得重複。
   • defaultLandingPageId：如果使用者點按這個廣告活動中的廣告，系統會將他們導向的到達網頁。您可以呼叫 advertiserLandingPages.list 來查詢現有到達網頁，或是呼叫 advertiserLandingPages.insert 來建立新到達網頁。
   • 開始和結束日期 - 這些日期必須是未來的時間，而且可以精準反映日期。詳情請參閱一般編碼資訊中的日期和時間項目符號。個別廣告日期可以超過結束日期，方便發布商在指定的廣告活動結束日期內履行指定動作合約。

   // Locate an advertiser landing page to use as a default.
   LandingPage defaultLandingPage = getAdvertiserLandingPage(reporting, profileId, advertiserId);
   
   // Create the campaign structure.
   Campaign campaign = new Campaign();
   campaign.setName(campaignName);
   campaign.setAdvertiserId(advertiserId);
   campaign.setArchived(false);
   campaign.setDefaultLandingPageId(defaultLandingPage.getId());
   
   // Set the campaign start date. This example uses today's date.
   Calendar today = Calendar.getInstance();
   DateTime startDate = new DateTime(true, today.getTimeInMillis(), null);
   campaign.setStartDate(startDate);
   
   // Set the campaign end date. This example uses one month from today's date.
   Calendar nextMonth = Calendar.getInstance();
   nextMonth.add(Calendar.MONTH, 1);
   DateTime endDate = new DateTime(true, nextMonth.getTimeInMillis(), null);
   campaign.setEndDate(endDate);
   

2. 呼叫 campaigns.insert() 儲存廣告活動。

   // Insert the campaign.
   Campaign result = reporting.campaigns().insert(profileId, campaign).execute();
   

PHP

1. 建立 Campaign 物件並設定必要屬性：

   • advertiserId：與這個廣告活動建立關聯的廣告客戶。
   • name - 這個廣告主的所有廣告活動皆不得重複。
   • defaultLandingPageId：如果使用者點按這個廣告活動中的廣告，系統會將他們導向的到達網頁。您可以呼叫 advertiserLandingPages.list 來查詢現有到達網頁，或是呼叫 advertiserLandingPages.insert 來建立新到達網頁。
   • 開始和結束日期 - 這些日期必須是未來的時間，而且可以精準反映日期。詳情請參閱一般編碼資訊中的日期和時間項目符號。個別廣告日期可以超過結束日期，方便發布商在指定的廣告活動結束日期內履行指定動作合約。

   $startDate = new DateTime('today');
   $endDate = new DateTime('+1 month');
   
   $campaign = new Google_Service_Dfareporting_Campaign();
   $campaign->setAdvertiserId($values['advertiser_id']);
   $campaign->setDefaultLandingPageId($values['default_landing_page_id']);
   $campaign->setName($values['campaign_name']);
   $campaign->setStartDate($startDate->format('Y-m-d'));
   $campaign->setEndDate($endDate->format('Y-m-d'));
   

2. 呼叫 campaigns.insert() 儲存廣告活動。

   $result = $this->service->campaigns->insert(
       $values['user_profile_id'],
       $campaign
   );
   

Python

1. 建立 Campaign 物件並設定必要屬性：

   • advertiserId：與這個廣告活動建立關聯的廣告客戶。
   • name - 這個廣告主的所有廣告活動皆不得重複。
   • defaultLandingPageId：如果使用者點按這個廣告活動中的廣告，系統會將他們導向的到達網頁。您可以呼叫 advertiserLandingPages.list 來查詢現有到達網頁，或是呼叫 advertiserLandingPages.insert 來建立新到達網頁。
   • 開始和結束日期 - 這些日期必須是未來的時間，而且可以精準反映日期。詳情請參閱一般編碼資訊中的日期和時間項目符號。個別廣告日期可以超過結束日期，方便發布商在指定的廣告活動結束日期內履行指定動作合約。

   # Locate an advertiser landing page to use as a default.
   default_landing_page = get_advertiser_landing_page(service, profile_id,
                                                      advertiser_id)
   
   # Construct and save campaign.
   campaign = {
       'name': 'Test Campaign #%s' % uuid.uuid4(),
       'advertiserId': advertiser_id,
       'archived': 'false',
       'defaultLandingPageId': default_landing_page['id'],
       'startDate': '2015-01-01',
       'endDate': '2020-01-01'
   }
   

2. 呼叫 campaigns.insert() 儲存廣告活動。

   request = service.campaigns().insert(profileId=profile_id, body=campaign)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 建立 Campaign 物件並設定必要屬性：

   • advertiserId：與這個廣告活動建立關聯的廣告客戶。
   • name - 這個廣告主的所有廣告活動皆不得重複。
   • defaultLandingPageId：如果使用者點按這個廣告活動中的廣告，系統會將他們導向的到達網頁。您可以呼叫 advertiserLandingPages.list 來查詢現有到達網頁，或是呼叫 advertiserLandingPages.insert 來建立新到達網頁。
   • 開始和結束日期 - 這些日期必須是未來的時間，而且可以精準反映日期。詳情請參閱一般編碼資訊中的日期和時間項目符號。個別廣告日期可以超過結束日期，方便發布商在指定的廣告活動結束日期內履行指定動作合約。

   # Locate an advertiser landing page to use as a default.
   default_landing_page = get_advertiser_landing_page(service, profile_id,
     advertiser_id)
   
   # Create a new campaign resource to insert.
   campaign = DfareportingUtils::API_NAMESPACE::Campaign.new(
     advertiser_id: advertiser_id,
     archived: false,
     default_landing_page_id: default_landing_page.id,
     name: format('Example Campaign #%s', SecureRandom.hex(3)),
     start_date: '2014-01-01',
     end_date: '2020-01-01'
   )
   

2. 呼叫 campaigns.insert() 儲存廣告活動。

   # Insert the campaign.
   result = service.insert_campaign(profile_id, campaign)
   

建立刊登位置

C#

1. 建立 Placement 物件並設定必要的刊登位置屬性 (包括 campaignId 和 siteId)。此外，請務必為您網站協議的刊登位置，正確設定刊登位置類型和大小。

   // Create the placement.
   Placement placement = new Placement();
   placement.Name = placementName;
   placement.CampaignId = campaignId;
   placement.Compatibility = "DISPLAY";
   placement.PaymentSource = "PLACEMENT_AGENCY_PAID";
   placement.SiteId = dfaSiteId;
   placement.TagFormats = new List<string>() { "PLACEMENT_TAG_STANDARD" };
   
   // Set the size of the placement.
   Size size = new Size();
   size.Id = sizeId;
   placement.Size = size;
   

2. 建立新的 PricingSchedule 物件並指派給刊登位置。

   // Set the pricing schedule for the placement.
   PricingSchedule pricingSchedule = new PricingSchedule();
   pricingSchedule.EndDate = campaign.EndDate;
   pricingSchedule.PricingType = "PRICING_TYPE_CPM";
   pricingSchedule.StartDate = campaign.StartDate;
   placement.PricingSchedule = pricingSchedule;
   

3. 呼叫 placements.insert() 來儲存 Placement 物件。請務必儲存傳回的 ID，以便用來指派給廣告或廣告素材。

   // Insert the placement.
   Placement result = service.Placements.Insert(placement, profileId).Execute();
   

Java

1. 建立 Placement 物件並設定必要的刊登位置屬性 (包括 campaignId 和 siteId)。此外，請務必為您網站協議的刊登位置，正確設定刊登位置類型和大小。

   // Create the placement.
   Placement placement = new Placement();
   placement.setName(placementName);
   placement.setCampaignId(campaignId);
   placement.setCompatibility("DISPLAY");
   placement.setPaymentSource("PLACEMENT_AGENCY_PAID");
   placement.setSiteId(dfaSiteId);
   placement.setTagFormats(ImmutableList.of("PLACEMENT_TAG_STANDARD"));
   
   // Set the size of the placement.
   Size size = new Size();
   size.setId(sizeId);
   placement.setSize(size);
   

2. 建立新的 PricingSchedule 物件並指派給刊登位置。

   // Set the pricing schedule for the placement.
   PricingSchedule pricingSchedule = new PricingSchedule();
   pricingSchedule.setEndDate(campaign.getEndDate());
   pricingSchedule.setPricingType("PRICING_TYPE_CPM");
   pricingSchedule.setStartDate(campaign.getStartDate());
   placement.setPricingSchedule(pricingSchedule);
   

3. 呼叫 placements.insert() 來儲存 Placement 物件。請務必儲存傳回的 ID，以便用來指派給廣告或廣告素材。

   // Insert the placement.
   Placement result = reporting.placements().insert(profileId, placement).execute();
   

PHP

1. 建立 Placement 物件並設定必要的刊登位置屬性 (包括 campaignId 和 siteId)。此外，請務必為您網站協議的刊登位置，正確設定刊登位置類型和大小。

   $placement = new Google_Service_Dfareporting_Placement();
   $placement->setCampaignId($values['campaign_id']);
   $placement->setCompatibility('DISPLAY');
   $placement->setName($values['placement_name']);
   $placement->setPaymentSource('PLACEMENT_AGENCY_PAID');
   $placement->setSiteId($values['site_id']);
   $placement->setTagFormats(['PLACEMENT_TAG_STANDARD']);
   
   // Set the size of the placement.
   $size = new Google_Service_Dfareporting_Size();
   $size->setId($values['size_id']);
   $placement->setSize($size);
   

2. 建立新的 PricingSchedule 物件並指派給刊登位置。

   // Set the pricing schedule for the placement.
   $pricingSchedule = new Google_Service_Dfareporting_PricingSchedule();
   $pricingSchedule->setEndDate($campaign->getEndDate());
   $pricingSchedule->setPricingType('PRICING_TYPE_CPM');
   $pricingSchedule->setStartDate($campaign->getStartDate());
   $placement->setPricingSchedule($pricingSchedule);
   

3. 呼叫 placements.insert() 來儲存 Placement 物件。請務必儲存傳回的 ID，以便用來指派給廣告或廣告素材。

   // Insert the placement.
   $result = $this->service->placements->insert(
       $values['user_profile_id'],
       $placement
   );
   

Python

1. 建立 Placement 物件並設定必要的刊登位置屬性 (包括 campaignId 和 siteId)。此外，請務必為您網站協議的刊登位置，正確設定刊登位置類型和大小。

   # Construct and save placement.
   placement = {
       'name': 'Test Placement',
       'campaignId': campaign_id,
       'compatibility': 'DISPLAY',
       'siteId': site_id,
       'size': {
           'height': '1',
           'width': '1'
       },
       'paymentSource': 'PLACEMENT_AGENCY_PAID',
       'tagFormats': ['PLACEMENT_TAG_STANDARD']
   }
   

2. 建立新的 PricingSchedule 物件並指派給刊登位置。

   # Set the pricing schedule for the placement.
   placement['pricingSchedule'] = {
       'startDate': campaign['startDate'],
       'endDate': campaign['endDate'],
       'pricingType': 'PRICING_TYPE_CPM'
   }
   

3. 呼叫 placements.insert() 來儲存 Placement 物件。請務必儲存傳回的 ID，以便用來指派給廣告或廣告素材。

   request = service.placements().insert(profileId=profile_id, body=placement)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 建立 Placement 物件並設定必要的刊登位置屬性 (包括 campaignId 和 siteId)。此外，請務必為您網站協議的刊登位置，正確設定刊登位置類型和大小。

   # Create a new placement resource to insert.
   placement = DfareportingUtils::API_NAMESPACE::Placement.new(
     campaign_id: campaign_id,
     compatibility: 'DISPLAY',
     name: 'Example Placement',
     payment_source: 'PLACEMENT_AGENCY_PAID',
     site_id: site_id,
     size: DfareportingUtils::API_NAMESPACE::Size.new(
       height: 1,
       width: 1
     ),
     tag_formats: ['PLACEMENT_TAG_STANDARD']
   )
   

2. 建立新的 PricingSchedule 物件並指派給刊登位置。

   # Set the pricing schedule for the placement.
   placement.pricing_schedule =
     DfareportingUtils::API_NAMESPACE::PricingSchedule.new(
       end_date: campaign.end_date,
       pricing_type: 'PRICING_TYPE_CPM',
       start_date: campaign.start_date
     )
   

3. 呼叫 placements.insert() 來儲存 Placement 物件。請務必儲存傳回的 ID，以便用來指派給廣告或廣告素材。

   # Insert the placement strategy.
   result = service.insert_placement(profile_id, placement)
   

上傳素材資源

您可以透過「媒體上傳」程序上傳多種類型的素材資源。雖然這個程序適用於所有廣告素材類型，但有些類型可能需要將特定屬性傳遞為中繼資料，才能正確使用。

C#

1. 建立 assetIdentifier 物件並設定必要屬性。無論使用哪種類型或使用方式，所有資產都必須指定 assetIdentifier。將素材資源指派至廣告素材時，這個物件就會用來參照素材資源。必要屬性包括：

   • name 屬性，將成為伺服器上資產的名稱。名稱必須包含用來表示檔案類型 (例如 .png 或 .gif) 的副檔名，並以資源名稱的形式在瀏覽器中顯示，但不必與原始檔案名稱相同。請注意，Campaign Manager 360 可能會變更這個名稱，在伺服器上改為專屬名稱；請檢查傳回值，確認該名稱是否已變更。
   • type 屬性，用於識別資產類型。這個屬性會決定與這個素材資源相關聯的廣告素材類型。

   // Create the creative asset ID and Metadata.
   CreativeAssetId assetId = new CreativeAssetId();
   assetId.Name = Path.GetFileName(assetFile);
   assetId.Type = assetType;
   

2. 呼叫 creativeAssets.insert() 來上傳檔案。執行多部分上傳，在同一個要求中同時傳遞 assetIdentifier 和檔案內容。如果成功，系統會傳回 CreativeAsset 資源以及 assetIdentifier，讓您將這個素材資源指派給廣告素材。

   // Prepare an input stream.
   FileStream assetContent = new FileStream(assetFile, FileMode.Open, FileAccess.Read);
   
   
   CreativeAssetMetadata metaData = new CreativeAssetMetadata();
   metaData.AssetIdentifier = assetId;
   
   // Insert the creative.
   String mimeType = determineMimeType(assetFile, assetType);
   CreativeAssetsResource.InsertMediaUpload request =
       Service.CreativeAssets.Insert(metaData, ProfileId, AdvertiserId, assetContent, mimeType);
   
   IUploadProgress progress = request.Upload();
   if (UploadStatus.Failed.Equals(progress.Status)) {
       throw progress.Exception;
   }
   

Java

1. 建立 assetIdentifier 物件並設定必要屬性。無論使用哪種類型或使用方式，所有資產都必須指定 assetIdentifier。將素材資源指派至廣告素材時，這個物件就會用來參照素材資源。必要屬性包括：

   • name 屬性，將成為伺服器上資產的名稱。名稱必須包含用來表示檔案類型 (例如 .png 或 .gif) 的副檔名，並以資源名稱的形式在瀏覽器中顯示，但不必與原始檔案名稱相同。請注意，Campaign Manager 360 可能會變更這個名稱，在伺服器上改為專屬名稱；請檢查傳回值，確認該名稱是否已變更。
   • type 屬性，用於識別資產類型。這個屬性會決定與這個素材資源相關聯的廣告素材類型。

   // Create the creative asset ID and Metadata.
   CreativeAssetId assetId = new CreativeAssetId();
   assetId.setName(assetName);
   assetId.setType(assetType);
   

2. 呼叫 creativeAssets.insert() 來上傳檔案。執行多部分上傳，在同一個要求中同時傳遞 assetIdentifier 和檔案內容。如果成功，系統會傳回 CreativeAsset 資源以及 assetIdentifier，讓您將這個素材資源指派給廣告素材。

   // Open the asset file.
   File file = new File(assetFile);
   
   // Prepare an input stream.
   String contentType = getMimeType(assetFile);
   InputStreamContent assetContent =
       new InputStreamContent(contentType, new BufferedInputStream(new FileInputStream(file)));
   assetContent.setLength(file.length());
   
   
   CreativeAssetMetadata metaData = new CreativeAssetMetadata();
   metaData.setAssetIdentifier(assetId);
   
   // Insert the creative.
   CreativeAssetMetadata result = reporting.creativeAssets()
       .insert(profileId, advertiserId, metaData, assetContent).execute();
   

PHP

1. 建立 assetIdentifier 物件並設定必要屬性。無論使用哪種類型或使用方式，所有資產都必須指定 assetIdentifier。將素材資源指派至廣告素材時，這個物件就會用來參照素材資源。必要屬性包括：

   • name 屬性，將成為伺服器上資產的名稱。名稱必須包含用來表示檔案類型 (例如 .png 或 .gif) 的副檔名，並以資源名稱的形式在瀏覽器中顯示，但不必與原始檔案名稱相同。請注意，Campaign Manager 360 可能會變更這個名稱，在伺服器上改為專屬名稱；請檢查傳回值，確認該名稱是否已變更。
   • type 屬性，用於識別資產類型。這個屬性會決定與這個素材資源相關聯的廣告素材類型。

   $assetId = new Google_Service_Dfareporting_CreativeAssetId();
   $assetId->setName($asset['name']);
   $assetId->setType($type);
   

2. 呼叫 creativeAssets.insert() 來上傳檔案。執行多部分上傳，在同一個要求中同時傳遞 assetIdentifier 和檔案內容。如果成功，系統會傳回 CreativeAsset 資源以及 assetIdentifier，讓您將這個素材資源指派給廣告素材。

   $metadata = new Google_Service_Dfareporting_CreativeAssetMetadata();
   $metadata->setAssetIdentifier($assetId);
   
   $result = $service->creativeAssets->insert(
       $userProfileId,
       $advertiserId,
       $metadata,
       ['data' => file_get_contents($asset['tmp_name']),
        'mimeType' => $asset['type'],
        'uploadType' => 'multipart']
   );
   

Python

1. 建立 assetIdentifier 物件並設定必要屬性。無論使用哪種類型或使用方式，所有資產都必須指定 assetIdentifier。將素材資源指派至廣告素材時，這個物件就會用來參照素材資源。必要屬性包括：

   • name 屬性，將成為伺服器上資產的名稱。名稱必須包含用來表示檔案類型 (例如 .png 或 .gif) 的副檔名，並以資源名稱的形式在瀏覽器中顯示，但不必與原始檔案名稱相同。請注意，Campaign Manager 360 可能會變更這個名稱，在伺服器上改為專屬名稱；請檢查傳回值，確認該名稱是否已變更。
   • type 屬性，用於識別資產類型。這個屬性會決定與這個素材資源相關聯的廣告素材類型。

   # Construct the creative asset metadata
   creative_asset = {'assetIdentifier': {'name': asset_name, 'type': asset_type}}
   

2. 呼叫 creativeAssets.insert() 來上傳檔案。執行多部分上傳，在同一個要求中同時傳遞 assetIdentifier 和檔案內容。如果成功，系統會傳回 CreativeAsset 資源以及 assetIdentifier，讓您將這個素材資源指派給廣告素材。

   media = MediaFileUpload(path_to_asset_file)
   if not media.mimetype():
     media = MediaFileUpload(path_to_asset_file, 'application/octet-stream')
   
   response = service.creativeAssets().insert(
       advertiserId=advertiser_id,
       profileId=profile_id,
       media_body=media,
       body=creative_asset).execute()
   

Ruby

1. 建立 assetIdentifier 物件並設定必要屬性。無論使用哪種類型或使用方式，所有資產都必須指定 assetIdentifier。將素材資源指派至廣告素材時，這個物件就會用來參照素材資源。必要屬性包括：

   • name 屬性，將成為伺服器上資產的名稱。名稱必須包含用來表示檔案類型 (例如 .png 或 .gif) 的副檔名，並以資源名稱的形式在瀏覽器中顯示，但不必與原始檔案名稱相同。請注意，Campaign Manager 360 可能會變更這個名稱，在伺服器上改為專屬名稱；請檢查傳回值，確認該名稱是否已變更。
   • type 屬性，用於識別資產類型。這個屬性會決定與這個素材資源相關聯的廣告素材類型。

   # Construct the creative asset metadata
   creative_asset = DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
     asset_identifier: DfareportingUtils::API_NAMESPACE::CreativeAssetId.new(
       name: asset_name,
       type: asset_type
     )
   )
   

2. 呼叫 creativeAssets.insert() 來上傳檔案。執行多部分上傳，在同一個要求中同時傳遞 assetIdentifier 和檔案內容。如果成功，系統會傳回 CreativeAsset 資源以及 assetIdentifier，讓您將這個素材資源指派給廣告素材。

   # Upload the asset.
   mime_type = determine_mime_type(path_to_asset_file, asset_type)
   
   result = @service.insert_creative_asset(
     @profile_id,
     advertiser_id,
     creative_asset,
     content_type: mime_type,
     upload_source: path_to_asset_file
   )
   

建立廣告素材

Creative 物件會包裝現有資產。您可以根據在代管頁面上使用廣告素材的方式，建立多種廣告素材類型的 Creative 物件。請參閱參考說明文件，找出適合您的類型。

以下範例說明如何建立新的 HTML5 多媒體廣告素材。

C#

1. 上傳素材資源。不同廣告素材所需的素材資源類型和數量各不相同，詳情請參閱上傳素材資源。每次成功上傳素材資源時，回應中都會出現 assetIdenfitier；您可以使用已儲存的檔案名稱和類型，在廣告素材中參照這些素材資源，而非使用傳統 ID。
2. 建立廣告素材並指定合適的值。對 Creative 執行個體化並設定適當的 type。請注意，Creative 物件在儲存後即無法變更類型。依 AssetIdentifier 和 role 指定資產。

   // Locate an advertiser landing page to use as a default.
   LandingPage defaultLandingPage = getAdvertiserLandingPage(service, profileId, advertiserId);
   
   // Create the creative structure.
   Creative creative = new Creative();
   creative.AdvertiserId = advertiserId;
   creative.Name = "Test HTML5 display creative";
   creative.Size = new Size() { Id = sizeId };
   creative.Type = "DISPLAY";
   
   // Upload the HTML5 asset.
   CreativeAssetUtils assetUtils = new CreativeAssetUtils(service, profileId, advertiserId);
   CreativeAssetId html5AssetId =
       assetUtils.uploadAsset(pathToHtml5AssetFile, "HTML").AssetIdentifier;
   
   CreativeAsset html5Asset = new CreativeAsset();
   html5Asset.AssetIdentifier = html5AssetId;
   html5Asset.Role = "PRIMARY";
   
   // Upload the backup image asset.
   CreativeAssetId imageAssetId =
       assetUtils.uploadAsset(pathToImageAssetFile, "HTML_IMAGE").AssetIdentifier;
   
   CreativeAsset imageAsset = new CreativeAsset();
   imageAsset.AssetIdentifier = imageAssetId;
   imageAsset.Role = "BACKUP_IMAGE";
   
   // Add the creative assets.
   creative.CreativeAssets = new List<CreativeAsset>() { html5Asset, imageAsset };
   
   // Configure the bacup image.
   creative.BackupImageClickThroughUrl = new CreativeClickThroughUrl() {
     LandingPageId = defaultLandingPage.Id
   };
   creative.BackupImageReportingLabel = "backup";
   creative.BackupImageTargetWindow = new TargetWindow() { TargetWindowOption = "NEW_WINDOW" };
   
   // Add a click tag.
   ClickTag clickTag = new ClickTag();
   clickTag.Name = "clickTag";
   clickTag.EventName = "exit";
   clickTag.ClickThroughUrl = new CreativeClickThroughUrl() {
     LandingPageId = defaultLandingPage.Id
   };
   creative.ClickTags = new List<ClickTag>() { clickTag };
   

3. 儲存廣告素材。只要呼叫 creatives.insert() 即可進行檢查。必須指定與這個廣告素材建立關聯的廣告主 ID。

   Creative result = service.Creatives.Insert(creative, profileId).Execute();
   

4. (選用) 將廣告素材與廣告活動建立關聯。方法是呼叫 campaignCreativeAssociations.insert()，並傳入廣告活動和廣告素材 ID。

   // Create the campaign creative association structure.
   CampaignCreativeAssociation association = new CampaignCreativeAssociation();
   association.CreativeId = creativeId;
   
   // Insert the association.
   CampaignCreativeAssociation result =
       service.CampaignCreativeAssociations.Insert(association, profileId, campaignId).Execute();
   

Java

1. 上傳素材資源。不同廣告素材所需的素材資源類型和數量各不相同，詳情請參閱上傳素材資源。每次成功上傳素材資源時，回應中都會出現 assetIdenfitier；您可以使用已儲存的檔案名稱和類型，在廣告素材中參照這些素材資源，而非使用傳統 ID。
2. 建立廣告素材並指定合適的值。對 Creative 執行個體化並設定適當的 type。請注意，Creative 物件在儲存後即無法變更類型。依 AssetIdentifier 和 role 指定資產。

   // Locate an advertiser landing page to use as a default.
   LandingPage defaultLandingPage = getAdvertiserLandingPage(reporting, profileId, advertiserId);
   
   // Create the creative structure.
   Creative creative = new Creative();
   creative.setAdvertiserId(advertiserId);
   creative.setName("Test HTML5 display creative");
   creative.setSize(new Size().setId(sizeId));
   creative.setType("DISPLAY");
   
   // Upload the HTML5 asset.
   CreativeAssetId html5AssetId = CreativeAssetUtils.uploadAsset(reporting, profileId,
       advertiserId, HTML5_ASSET_NAME, PATH_TO_HTML5_ASSET_FILE, "HTML").getAssetIdentifier();
   
   CreativeAsset html5Asset =
       new CreativeAsset().setAssetIdentifier(html5AssetId).setRole("PRIMARY");
   
   // Upload the backup image asset (note: asset type must be set to HTML_IMAGE).
   CreativeAssetId imageAssetId = CreativeAssetUtils.uploadAsset(reporting, profileId,
       advertiserId, IMAGE_ASSET_NAME, PATH_TO_IMAGE_ASSET_FILE, "HTML_IMAGE")
       .getAssetIdentifier();
   
   CreativeAsset backupImageAsset =
       new CreativeAsset().setAssetIdentifier(imageAssetId).setRole("BACKUP_IMAGE");
   
   // Add the creative assets.
   creative.setCreativeAssets(ImmutableList.of(html5Asset, backupImageAsset));
   
   // Configure the backup image.
   creative.setBackupImageClickThroughUrl(
       new CreativeClickThroughUrl().setLandingPageId(defaultLandingPage.getId()));
   creative.setBackupImageReportingLabel("backup");
   creative.setBackupImageTargetWindow(new TargetWindow().setTargetWindowOption("NEW_WINDOW"));
   
   // Add a click tag.
   ClickTag clickTag =
       new ClickTag().setName("clickTag").setEventName("exit").setClickThroughUrl(
           new CreativeClickThroughUrl().setLandingPageId(defaultLandingPage.getId()));
   creative.setClickTags(ImmutableList.of(clickTag));
   

3. 儲存廣告素材。只要呼叫 creatives.insert() 即可進行檢查。必須指定與這個廣告素材建立關聯的廣告主 ID。

   Creative result = reporting.creatives().insert(profileId, creative).execute();
   

4. (選用) 將廣告素材與廣告活動建立關聯。方法是呼叫 campaignCreativeAssociations.insert()，並傳入廣告活動和廣告素材 ID。

   // Create the campaign creative association structure.
   CampaignCreativeAssociation association = new CampaignCreativeAssociation();
   association.setCreativeId(creativeId);
   
   // Insert the association.
   CampaignCreativeAssociation result = reporting
       .campaignCreativeAssociations().insert(profileId, campaignId, association)
       .execute();
   

PHP

1. 上傳素材資源。不同廣告素材所需的素材資源類型和數量各不相同，詳情請參閱上傳素材資源。每次成功上傳素材資源時，回應中都會出現 assetIdenfitier；您可以使用已儲存的檔案名稱和類型，在廣告素材中參照這些素材資源，而非使用傳統 ID。
2. 建立廣告素材並指定合適的值。對 Creative 執行個體化並設定適當的 type。請注意，Creative 物件在儲存後即無法變更類型。依 AssetIdentifier 和 role 指定資產。

   $creative = new Google_Service_Dfareporting_Creative();
   $creative->setAdvertiserId($values['advertiser_id']);
   $creative->setAutoAdvanceImages(true);
   $creative->setName('Test HTML5 display creative');
   $creative->setType('DISPLAY');
   
   $size = new Google_Service_Dfareporting_Size();
   $size->setId($values['size_id']);
   $creative->setSize($size);
   
   // Upload the HTML5 asset.
   $html = uploadAsset(
       $this->service,
       $values['user_profile_id'],
       $values['advertiser_id'],
       $values['html_asset_file'],
       'HTML'
   );
   
   $htmlAsset = new Google_Service_Dfareporting_CreativeAsset();
   $htmlAsset->setAssetIdentifier($html->getAssetIdentifier());
   $htmlAsset->setRole('PRIMARY');
   
   // Upload the backup image asset.
   $image = uploadAsset(
       $this->service,
       $values['user_profile_id'],
       $values['advertiser_id'],
       $values['image_asset_file'],
       'HTML_IMAGE'
   );
   
   $imageAsset = new Google_Service_Dfareporting_CreativeAsset();
   $imageAsset->setAssetIdentifier($image->getAssetIdentifier());
   $imageAsset->setRole('BACKUP_IMAGE');
   
   // Add the creative assets.
   $creative->setCreativeAssets([$htmlAsset, $imageAsset]);
   
   // Configure the default click-through URL.
   $clickThroughUrl =
       new Google_Service_Dfareporting_CreativeClickThroughUrl();
   $clickThroughUrl->setLandingPageId($values['landing_page_id']);
   
   // Configure the backup image.
   $creative->setBackupImageClickThroughUrl($clickThroughUrl);
   $creative->setBackupImageReportingLabel('backup');
   
   $targetWindow = new Google_Service_Dfareporting_TargetWindow();
   $targetWindow->setTargetWindowOption('NEW_WINDOW');
   $creative->setBackupImageTargetWindow($targetWindow);
   
   // Add a click tag.
   $clickTag = new Google_Service_Dfareporting_ClickTag();
   $clickTag->setName('clickTag');
   $clickTag->setEventName('exit');
   $clickTag->setClickThroughUrl($clickThroughUrl);
   $creative->setClickTags([$clickTag]);
   

3. 儲存廣告素材。只要呼叫 creatives.insert() 即可進行檢查。必須指定與這個廣告素材建立關聯的廣告主 ID。

   $result = $this->service->creatives->insert(
       $values['user_profile_id'],
       $creative
   );
   

4. (選用) 將廣告素材與廣告活動建立關聯。方法是呼叫 campaignCreativeAssociations.insert()，並傳入廣告活動和廣告素材 ID。

   $association =
       new Google_Service_Dfareporting_CampaignCreativeAssociation();
   $association->setCreativeId($values['creative_id']);
   
   $result = $this->service->campaignCreativeAssociations->insert(
       $values['user_profile_id'],
       $values['campaign_id'],
       $association
   );
   

Python

1. 上傳素材資源。不同廣告素材所需的素材資源類型和數量各不相同，詳情請參閱上傳素材資源。每次成功上傳素材資源時，回應中都會出現 assetIdenfitier；您可以使用已儲存的檔案名稱和類型，在廣告素材中參照這些素材資源，而非使用傳統 ID。
2. 建立廣告素材並指定合適的值。對 Creative 執行個體化並設定適當的 type。請注意，Creative 物件在儲存後即無法變更類型。依 AssetIdentifier 和 role 指定資產。

   # Locate an advertiser landing page to use as a default.
   default_landing_page = get_advertiser_landing_page(service, profile_id,
                                                      advertiser_id)
   
   # Upload the HTML5 asset
   html5_asset_id = upload_creative_asset(service, profile_id, advertiser_id,
                                          html5_asset_name,
                                          path_to_html5_asset_file, 'HTML')
   
   # Upload the backup image asset
   backup_image_asset_id = upload_creative_asset(
       service, profile_id, advertiser_id, backup_image_name,
       path_to_backup_image_file, 'HTML_IMAGE')
   
   # Construct the creative structure.
   creative = {
       'advertiserId': advertiser_id,
       'backupImageClickThroughUrl': {
           'landingPageId': default_landing_page['id']
       },
       'backupImageReportingLabel': 'backup_image_exit',
       'backupImageTargetWindow': {'targetWindowOption': 'NEW_WINDOW'},
       'clickTags': [{
           'eventName': 'exit',
           'name': 'click_tag',
           'clickThroughUrl': {'landingPageId': default_landing_page['id']}
       }],
       'creativeAssets': [
           {'assetIdentifier': html5_asset_id, 'role': 'PRIMARY'},
           {'assetIdentifier': backup_image_asset_id, 'role': 'BACKUP_IMAGE'}
       ],
       'name': 'Test HTML5 display creative',
       'size': {'id': size_id},
       'type': 'DISPLAY'
   }
   

3. 儲存廣告素材。只要呼叫 creatives.insert() 即可進行檢查。必須指定與這個廣告素材建立關聯的廣告主 ID。

   request = service.creatives().insert(profileId=profile_id, body=creative)
   
   # Execute request and print response.
   response = request.execute()
   

4. (選用) 將廣告素材與廣告活動建立關聯。方法是呼叫 campaignCreativeAssociations.insert()，並傳入廣告活動和廣告素材 ID。

   # Construct the request.
   association = {
       'creativeId': creative_id
   }
   
   request = service.campaignCreativeAssociations().insert(
       profileId=profile_id, campaignId=campaign_id, body=association)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 上傳素材資源。不同廣告素材所需的素材資源類型和數量各不相同，詳情請參閱上傳素材資源。每次成功上傳素材資源時，回應中都會出現 assetIdenfitier；您可以使用已儲存的檔案名稱和類型，在廣告素材中參照這些素材資源，而非使用傳統 ID。
2. 建立廣告素材並指定合適的值。對 Creative 執行個體化並設定適當的 type。請注意，Creative 物件在儲存後即無法變更類型。依 AssetIdentifier 和 role 指定資產。

   # Locate an advertiser landing page to use as a default.
   default_landing_page = get_advertiser_landing_page(service, profile_id,
     advertiser_id)
   
   # Upload the HTML5 asset.
   html5_asset_id = util.upload_asset(advertiser_id, path_to_html5_asset_file,
     'HTML').asset_identifier
   
   # Upload the backup image asset.
   backup_image_asset_id = util.upload_asset(advertiser_id,
     path_to_backup_image_file, 'HTML_IMAGE').asset_identifier
   
   # Construct the creative structure.
   creative = DfareportingUtils::API_NAMESPACE::Creative.new(
     advertiser_id: advertiser_id,
     backup_image_click_through_url:
       DfareportingUtils::API_NAMESPACE::CreativeClickThroughUrl.new(
         landing_page_id: default_landing_page.id
       ),
     backup_image_reporting_label: 'backup',
     backup_image_target_window:
       DfareportingUtils::API_NAMESPACE::TargetWindow.new(
         target_window_option: 'NEW_WINDOW'
       ),
     click_tags: [
       DfareportingUtils::API_NAMESPACE::ClickTag.new(
         event_name: 'exit',
         name: 'click_tag',
         click_through_url:
           DfareportingUtils::API_NAMESPACE::CreativeClickThroughUrl.new(
             landing_page_id: default_landing_page.id
           )
       )
     ],
     creative_assets: [
       DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
         asset_identifier: html5_asset_id,
         role: 'PRIMARY'
       ),
       DfareportingUtils::API_NAMESPACE::CreativeAsset.new(
         asset_identifier: backup_image_asset_id,
         role: 'BACKUP_IMAGE'
       )
     ],
     name: 'Example HTML5 display creative',
     size: DfareportingUtils::API_NAMESPACE::Size.new(id: size_id),
     type: 'DISPLAY'
   )
   

3. 儲存廣告素材。只要呼叫 creatives.insert() 即可進行檢查。必須指定與這個廣告素材建立關聯的廣告主 ID。

   # Insert the creative.
   result = service.insert_creative(profile_id, creative)
   

4. (選用) 將廣告素材與廣告活動建立關聯。方法是呼叫 campaignCreativeAssociations.insert()，並傳入廣告活動和廣告素材 ID。

   # Create a new creative-campaign association to insert
   association =
     DfareportingUtils::API_NAMESPACE::CampaignCreativeAssociation.new(
       creative_id: creative_id
     )
   
   # Insert the advertiser group.
   result = service.insert_campaign_creative_association(profile_id, campaign_id,
     association)
   

製作廣告

Ad 是 Creative 和 Placement 之間的連結。Ad 可連結至一或多個刊登位置，並包含一或多個廣告素材。

您可以用明確或隱含的方式建立 Ad。

明確

C#

1. 為與這則廣告相關聯的每個廣告素材建立 CreativeAssignment 物件。請務必將 CreativeAssignment.active 欄位設為 true。

   // Create a click-through URL.
   ClickThroughUrl clickThroughUrl = new ClickThroughUrl();
   clickThroughUrl.DefaultLandingPage = true;
   
   // Create a creative assignment.
   CreativeAssignment creativeAssignment = new CreativeAssignment();
   creativeAssignment.Active = true;
   creativeAssignment.CreativeId = creativeId;
   creativeAssignment.ClickThroughUrl = clickThroughUrl;
   

2. 建立 CreativeRotation 物件以儲存 CreativeAssignment。如果您建立輪播群組，請務必設定其他必要的廣告素材輪播欄位。

   // Create a creative rotation.
   CreativeRotation creativeRotation = new CreativeRotation();
   creativeRotation.CreativeAssignments = new List<CreativeAssignment>() {
       creativeAssignment
   };
   

3. 為與這個廣告相關聯的每個刊登位置建立 PlacementAssignment 物件。請務必將 PlacementAssignment.active 欄位設為 true。

   // Create a placement assignment.
   PlacementAssignment placementAssignment = new PlacementAssignment();
   placementAssignment.Active = true;
   placementAssignment.PlacementId = placementId;
   

4. 建立 Ad 物件。將 creativeRotation 設為 Ad 物件的 creativeRotation 欄位，並將 PlacementAssignments 設為 Ad 物件的 placementAssignments 陣列。

   // Create a delivery schedule.
   DeliverySchedule deliverySchedule = new DeliverySchedule();
   deliverySchedule.ImpressionRatio = 1;
   deliverySchedule.Priority = "AD_PRIORITY_01";
   
   DateTime startDate = DateTime.Now;
   DateTime endDate = Convert.ToDateTime(campaign.EndDate);
   
   // Create a rotation group.
   Ad rotationGroup = new Ad();
   rotationGroup.Active = true;
   rotationGroup.CampaignId = campaignId;
   rotationGroup.CreativeRotation = creativeRotation;
   rotationGroup.DeliverySchedule = deliverySchedule;
   rotationGroup.StartTime = startDate;
   rotationGroup.EndTime = endDate;
   rotationGroup.Name = adName;
   rotationGroup.PlacementAssignments = new List<PlacementAssignment>() {
       placementAssignment
   };
   rotationGroup.Type = "AD_SERVING_STANDARD_AD";
   

5. 呼叫 ads.insert() 來儲存廣告。

   // Insert the rotation group.
   Ad result = service.Ads.Insert(rotationGroup, profileId).Execute();
   

Java

1. 為與這則廣告相關聯的每個廣告素材建立 CreativeAssignment 物件。請務必將 CreativeAssignment.active 欄位設為 true。

   // Create a click-through URL.
   ClickThroughUrl clickThroughUrl = new ClickThroughUrl();
   clickThroughUrl.setDefaultLandingPage(true);
   
   // Create a creative assignment.
   CreativeAssignment creativeAssignment = new CreativeAssignment();
   creativeAssignment.setActive(true);
   creativeAssignment.setCreativeId(creativeId);
   creativeAssignment.setClickThroughUrl(clickThroughUrl);
   

2. 建立 CreativeRotation 物件以儲存 CreativeAssignment。如果您建立輪播群組，請務必設定其他必要的廣告素材輪播欄位。

   // Create a creative rotation.
   CreativeRotation creativeRotation = new CreativeRotation();
   creativeRotation.setCreativeAssignments(ImmutableList.of(creativeAssignment));
   

3. 為與這個廣告相關聯的每個刊登位置建立 PlacementAssignment 物件。請務必將 PlacementAssignment.active 欄位設為 true。

   // Create a placement assignment.
   PlacementAssignment placementAssignment = new PlacementAssignment();
   placementAssignment.setActive(true);
   placementAssignment.setPlacementId(placementId);
   

4. 建立 Ad 物件。將 creativeRotation 設為 Ad 物件的 creativeRotation 欄位，並將 PlacementAssignments 設為 Ad 物件的 placementAssignments 陣列。

   // Create a delivery schedule.
   DeliverySchedule deliverySchedule = new DeliverySchedule();
   deliverySchedule.setImpressionRatio(1L);
   deliverySchedule.setPriority("AD_PRIORITY_01");
   
   DateTime startDate = new DateTime(new Date());
   DateTime endDate = new DateTime(campaign.getEndDate().getValue());
   
   // Create a rotation group.
   Ad rotationGroup = new Ad();
   rotationGroup.setActive(true);
   rotationGroup.setCampaignId(campaignId);
   rotationGroup.setCreativeRotation(creativeRotation);
   rotationGroup.setDeliverySchedule(deliverySchedule);
   rotationGroup.setStartTime(startDate);
   rotationGroup.setEndTime(endDate);
   rotationGroup.setName(adName);
   rotationGroup.setPlacementAssignments(ImmutableList.of(placementAssignment));
   rotationGroup.setType("AD_SERVING_STANDARD_AD");
   

5. 呼叫 ads.insert() 來儲存廣告。

   // Insert the rotation group.
   Ad result = reporting.ads().insert(profileId, rotationGroup).execute();
   

PHP

1. 為與這則廣告相關聯的每個廣告素材建立 CreativeAssignment 物件。請務必將 CreativeAssignment.active 欄位設為 true。

   // Create a click-through URL.
   $url = new Google_Service_Dfareporting_ClickThroughUrl();
   $url->setDefaultLandingPage(true);
   
   // Create a creative assignment.
   $creativeAssignment =
       new Google_Service_Dfareporting_CreativeAssignment();
   $creativeAssignment->setActive(true);
   $creativeAssignment->setCreativeId($values['creative_id']);
   $creativeAssignment->setClickThroughUrl($url);
   

2. 建立 CreativeRotation 物件以儲存 CreativeAssignment。如果您建立輪播群組，請務必設定其他必要的廣告素材輪播欄位。

   // Create a creative rotation.
   $creativeRotation = new Google_Service_Dfareporting_CreativeRotation();
   $creativeRotation->setCreativeAssignments([$creativeAssignment]);
   

3. 為與這個廣告相關聯的每個刊登位置建立 PlacementAssignment 物件。請務必將 PlacementAssignment.active 欄位設為 true。

   // Create a placement assignment.
   $placementAssignment =
       new Google_Service_Dfareporting_PlacementAssignment();
   $placementAssignment->setActive(true);
   $placementAssignment->setPlacementId($values['placement_id']);
   

4. 建立 Ad 物件。將 creativeRotation 設為 Ad 物件的 creativeRotation 欄位，並將 PlacementAssignments 設為 Ad 物件的 placementAssignments 陣列。

   // Create a delivery schedule.
   $deliverySchedule = new Google_Service_Dfareporting_DeliverySchedule();
   $deliverySchedule->setImpressionRatio(1);
   $deliverySchedule->SetPriority('AD_PRIORITY_01');
   
   $startDate = new DateTime('today');
   $endDate = new DateTime($campaign->getEndDate());
   
   // Create a rotation group.
   $ad = new Google_Service_Dfareporting_Ad();
   $ad->setActive(true);
   $ad->setCampaignId($values['campaign_id']);
   $ad->setCreativeRotation($creativeRotation);
   $ad->setDeliverySchedule($deliverySchedule);
   $ad->setStartTime($startDate->format('Y-m-d') . 'T23:59:59Z');
   $ad->setEndTime($endDate->format('Y-m-d') . 'T00:00:00Z');
   $ad->setName($values['ad_name']);
   $ad->setPlacementAssignments([$placementAssignment]);
   $ad->setType('AD_SERVING_STANDARD_AD');
   

5. 呼叫 ads.insert() 來儲存廣告。

   $result = $this->service->ads->insert($values['user_profile_id'], $ad);
   

Python

1. 為與這則廣告相關聯的每個廣告素材建立 CreativeAssignment 物件。請務必將 CreativeAssignment.active 欄位設為 true。

   # Construct creative assignment.
   creative_assignment = {
       'active': 'true',
       'creativeId': creative_id,
       'clickThroughUrl': {
           'defaultLandingPage': 'true'
       }
   }
   

2. 建立 CreativeRotation 物件以儲存 CreativeAssignment。如果您建立輪播群組，請務必設定其他必要的廣告素材輪播欄位。

   # Construct creative rotation.
   creative_rotation = {
       'creativeAssignments': [creative_assignment],
       'type': 'CREATIVE_ROTATION_TYPE_RANDOM',
       'weightCalculationStrategy': 'WEIGHT_STRATEGY_OPTIMIZED'
   }
   

3. 為與這個廣告相關聯的每個刊登位置建立 PlacementAssignment 物件。請務必將 PlacementAssignment.active 欄位設為 true。

   # Construct placement assignment.
   placement_assignment = {
       'active': 'true',
       'placementId': placement_id,
   }
   

4. 建立 Ad 物件。將 creativeRotation 設為 Ad 物件的 creativeRotation 欄位，並將 PlacementAssignments 設為 Ad 物件的 placementAssignments 陣列。

   # Construct delivery schedule.
   delivery_schedule = {
       'impressionRatio': '1',
       'priority': 'AD_PRIORITY_01'
   }
   
   # Construct and save ad.
   ad = {
       'active': 'true',
       'campaignId': campaign_id,
       'creativeRotation': creative_rotation,
       'deliverySchedule': delivery_schedule,
       'endTime': '%sT00:00:00Z' % campaign['endDate'],
       'name': 'Test Rotation Group',
       'placementAssignments': [placement_assignment],
       'startTime': '%sT23:59:59Z' % time.strftime('%Y-%m-%d'),
       'type': 'AD_SERVING_STANDARD_AD'
   }
   

5. 呼叫 ads.insert() 來儲存廣告。

   request = service.ads().insert(profileId=profile_id, body=ad)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 為與這則廣告相關聯的每個廣告素材建立 CreativeAssignment 物件。請務必將 CreativeAssignment.active 欄位設為 true。

   # Construct creative assignment.
   creative_assignment =
     DfareportingUtils::API_NAMESPACE::CreativeAssignment.new(
       active: true,
       creative_id: creative_id,
       click_through_url: DfareportingUtils::API_NAMESPACE::ClickThroughUrl.new(
         default_landing_page: true
       )
     )
   

2. 建立 CreativeRotation 物件以儲存 CreativeAssignment。如果您建立輪播群組，請務必設定其他必要的廣告素材輪播欄位。

   # Construct creative rotation.
   creative_rotation = DfareportingUtils::API_NAMESPACE::CreativeRotation.new(
     creative_assignments: [creative_assignment],
     type: 'CREATIVE_ROTATION_TYPE_RANDOM',
     weight_calculation_strategy: 'WEIGHT_STRATEGY_OPTIMIZED'
   )
   

3. 為與這個廣告相關聯的每個刊登位置建立 PlacementAssignment 物件。請務必將 PlacementAssignment.active 欄位設為 true。

   # Construct placement assignment.
   placement_assignment =
     DfareportingUtils::API_NAMESPACE::PlacementAssignment.new(
       active: true,
       placement_id: placement_id
     )
   

4. 建立 Ad 物件。將 creativeRotation 設為 Ad 物件的 creativeRotation 欄位，並將 PlacementAssignments 設為 Ad 物件的 placementAssignments 陣列。

   # Construct delivery schedule.
   delivery_schedule = DfareportingUtils::API_NAMESPACE::DeliverySchedule.new(
     impression_ratio: 1,
     priority: 'AD_PRIORITY_01'
   )
   
   # Construct and save ad.
   ad = DfareportingUtils::API_NAMESPACE::Ad.new(
     active: true,
     campaign_id: campaign_id,
     creative_rotation: creative_rotation,
     delivery_schedule: delivery_schedule,
     end_time: format('%sT00:00:00Z', campaign.end_date),
     name: 'Example Rotation Group',
     placement_assignments: [placement_assignment],
     start_time: format('%sT23:59:59Z', Time.now.strftime('%Y-%m-%d')),
     type: 'AD_SERVING_STANDARD_AD'
   )
   

5. 呼叫 ads.insert() 來儲存廣告。

   result = service.insert_ad(profile_id, ad)
   

隱含

C#

1. 建立並儲存 Placement。
2. 建立並儲存 Creative。
3. 呼叫 campaignCreativeAssociations.insert()，將 Creative 與用於 Placement 的 Campaign 建立關聯 (請參閱「建立廣告素材」一節的步驟 4)。這樣做會建立一個與廣告素材和刊登位置相關聯的預設廣告。

   // Create the campaign creative association structure.
   CampaignCreativeAssociation association = new CampaignCreativeAssociation();
   association.CreativeId = creativeId;
   
   // Insert the association.
   CampaignCreativeAssociation result =
       service.CampaignCreativeAssociations.Insert(association, profileId, campaignId).Execute();
   

Java

1. 建立並儲存 Placement。
2. 建立並儲存 Creative。
3. 呼叫 campaignCreativeAssociations.insert()，將 Creative 與用於 Placement 的 Campaign 建立關聯 (請參閱「建立廣告素材」一節的步驟 4)。這樣做會建立一個與廣告素材和刊登位置相關聯的預設廣告。

   // Create the campaign creative association structure.
   CampaignCreativeAssociation association = new CampaignCreativeAssociation();
   association.setCreativeId(creativeId);
   
   // Insert the association.
   CampaignCreativeAssociation result = reporting
       .campaignCreativeAssociations().insert(profileId, campaignId, association)
       .execute();
   

PHP

1. 建立並儲存 Placement。
2. 建立並儲存 Creative。
3. 呼叫 campaignCreativeAssociations.insert()，將 Creative 與用於 Placement 的 Campaign 建立關聯 (請參閱「建立廣告素材」一節的步驟 4)。這樣做會建立一個與廣告素材和刊登位置相關聯的預設廣告。

   $association =
       new Google_Service_Dfareporting_CampaignCreativeAssociation();
   $association->setCreativeId($values['creative_id']);
   
   $result = $this->service->campaignCreativeAssociations->insert(
       $values['user_profile_id'],
       $values['campaign_id'],
       $association
   );
   

Python

1. 建立並儲存 Placement。
2. 建立並儲存 Creative。
3. 呼叫 campaignCreativeAssociations.insert()，將 Creative 與用於 Placement 的 Campaign 建立關聯 (請參閱「建立廣告素材」一節的步驟 4)。這樣做會建立一個與廣告素材和刊登位置相關聯的預設廣告。

   # Construct the request.
   association = {
       'creativeId': creative_id
   }
   
   request = service.campaignCreativeAssociations().insert(
       profileId=profile_id, campaignId=campaign_id, body=association)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 建立並儲存 Placement。
2. 建立並儲存 Creative。
3. 呼叫 campaignCreativeAssociations.insert()，將 Creative 與用於 Placement 的 Campaign 建立關聯 (請參閱「建立廣告素材」一節的步驟 4)。這樣做會建立一個與廣告素材和刊登位置相關聯的預設廣告。

   # Create a new creative-campaign association to insert
   association =
     DfareportingUtils::API_NAMESPACE::CampaignCreativeAssociation.new(
       creative_id: creative_id
     )
   
   # Insert the advertiser group.
   result = service.insert_campaign_creative_association(profile_id, campaign_id,
     association)
   

建立廣告可讓您省下建立 Ad 的額外步驟。請注意，只有在廣告活動中沒有指定大小的預設廣告時，才能執行這項操作。

搜尋物件

如要搜尋物件，您可以呼叫服務所公開的 list() 作業；該作業會定義要尋找的物件，並指定適用於該物件類型的選用條件。例如，如要搜尋 Ad 物件，您需要呼叫 ads.list()。選擇性標準會顯示適用於該物件的一組屬性，盡可能填寫您想搜尋的屬性。搜尋只會傳回符合「所有」條件的物件，您無法搜尋任何相符的條件。字串支援 * 萬用字元，不區分大小寫，且可在大型字串中進行比對。

如要提升效能，您可以使用 fields 參數要求部分回應。這會指示伺服器只傳回您指定的欄位，而非完整的資源表示法。如要進一步瞭解這個主題，請參閱「成效提示」指南。

Paging

有時候，不建議擷取 list() 要求的所有結果。比如說，您可能只想看數以千計的最新 10 個最新廣告。為瞭解決這個問題，許多 list() 方法可讓您透過 分頁 程序要求較少的結果。

使用分頁方法時，系統會在稱為「頁面」的群組中傳回部分結果。每頁結果數量上限為 1,000 個 (預設值)。您可以設定 maxResults 來變更每頁的結果數量，以及使用回應中傳回的 nextPageToken，疊代整個網頁：

C#

// Limit the fields returned.
String fields = "nextPageToken,ads(advertiserId,id,name)";

AdsListResponse result;
String nextPageToken = null;

do {
  // Create and execute the ad list request.
  AdsResource.ListRequest request = service.Ads.List(profileId);
  request.Active = true;
  request.Fields = fields;
  request.PageToken = nextPageToken;
  result = request.Execute();

  foreach (Ad ad in result.Ads) {
    Console.WriteLine(
        "Ad with ID {0} and name \"{1}\" is associated with advertiser" +
        " ID {2}.", ad.Id, ad.Name, ad.AdvertiserId);
  }

  // Update the next page token.
  nextPageToken = result.NextPageToken;
} while (result.Ads.Any() && !String.IsNullOrEmpty(nextPageToken));

Java

// Limit the fields returned.
String fields = "nextPageToken,ads(advertiserId,id,name)";

AdsListResponse result;
String nextPageToken = null;

do {
  // Create and execute the ad list request.
  result = reporting.ads().list(profileId).setActive(true).setFields(fields)
      .setPageToken(nextPageToken).execute();

  for (Ad ad : result.getAds()) {
    System.out.printf(
        "Ad with ID %d and name \"%s\" is associated with advertiser ID %d.%n", ad.getId(),
        ad.getName(), ad.getAdvertiserId());
  }

  // Update the next page token.
  nextPageToken = result.getNextPageToken();
} while (!result.getAds().isEmpty() && !Strings.isNullOrEmpty(nextPageToken));

PHP

$response = null;
$pageToken = null;

do {
    // Create and execute the ads list request.
    $response = $this->service->ads->listAds(
        $values['user_profile_id'],
        ['active' => true, 'pageToken' => $pageToken]
    );

    foreach ($response->getAds() as $ads) {
        $this->printResultsTableRow($ads);
    }

    // Update the next page token.
    $pageToken = $response->getNextPageToken();
} while (!empty($response->getAds()) && !empty($pageToken));

Python

# Construct the request.
request = service.ads().list(profileId=profile_id, active=True)

while True:
  # Execute request and print response.
  response = request.execute()

  for ad in response['ads']:
    print 'Found ad with ID %s and name "%s".' % (ad['id'], ad['name'])

  if response['ads'] and response['nextPageToken']:
    request = service.ads().list_next(request, response)
  else:
    break

Ruby

token = nil
loop do
  result = service.list_ads(profile_id,
    page_token: token,
    fields: 'nextPageToken,ads(id,name)')

  # Display results.
  if result.ads.any?
    result.ads.each do |ad|
      puts format('Found ad with ID %d and name "%s".', ad.id, ad.name)
    end

    token = result.next_page_token
  else
    # Stop paging if there are no more results.
    token = nil
  end

  break if token.to_s.empty?
end

產生 Floodlight 代碼

Floodlight 代碼是內嵌於網頁中的 HTML 代碼，用來追蹤使用者在網站上進行的動作 (例如購物)。如要產生 Floodlight 代碼，您需要屬於 FloodlightActivityGroup 的 FloodlightActivity：

C#

1. 建立新的 Floodlight 活動群組，傳入 name、type 和 floodlightConfigurationId 的值。

   // Create the floodlight activity group.
   FloodlightActivityGroup floodlightActivityGroup = new FloodlightActivityGroup();
   floodlightActivityGroup.Name = groupName;
   floodlightActivityGroup.FloodlightConfigurationId = floodlightConfigurationId;
   floodlightActivityGroup.Type = "COUNTER";
   

2. 呼叫 floodlightActivityGroups.insert() 以儲存 Floodlight 活動群組，呼叫會傳回新群組的 ID。

   // Insert the activity group.
   FloodlightActivityGroup result =
       service.FloodlightActivityGroups.Insert(floodlightActivityGroup, profileId).Execute();
   

3. 建立新的 Floodlight 活動，並指派剛建立的 Floodlight 活動群組 ID 以及所有其他必填欄位。

   // Set floodlight activity structure.
   FloodlightActivity activity = new FloodlightActivity();
   activity.CountingMethod = "STANDARD_COUNTING";
   activity.Name = activityName;
   activity.FloodlightActivityGroupId = activityGroupId;
   activity.FloodlightTagType = "GLOBAL_SITE_TAG";
   activity.ExpectedUrl = url;
   

4. 呼叫 floodlightActivities.insert() 即可儲存新活動，以便傳回新活動的 ID。

   // Create the floodlight tag activity.
   FloodlightActivity result =
       service.FloodlightActivities.Insert(activity, profileId).Execute();
   

5. 使用新活動的 floodlightActivityId 呼叫 floodlightActivities.generatetag() 來產生標記。將代碼傳送給廣告客戶網站的網站管理員。

   // Generate the floodlight activity tag.
   FloodlightActivitiesResource.GeneratetagRequest request =
       service.FloodlightActivities.Generatetag(profileId);
   request.FloodlightActivityId = activityId;
   
   FloodlightActivitiesGenerateTagResponse response = request.Execute();
   

Java

1. 建立新的 Floodlight 活動群組，傳入 name、type 和 floodlightConfigurationId 的值。

   // Create the floodlight activity group.
   FloodlightActivityGroup floodlightActivityGroup = new FloodlightActivityGroup();
   floodlightActivityGroup.setName(groupName);
   floodlightActivityGroup.setFloodlightConfigurationId(floodlightConfigurationId);
   floodlightActivityGroup.setType("COUNTER");
   

2. 呼叫 floodlightActivityGroups.insert() 以儲存 Floodlight 活動群組，呼叫會傳回新群組的 ID。

   // Insert the activity group.
   FloodlightActivityGroup result =
       reporting.floodlightActivityGroups().insert(profileId, floodlightActivityGroup).execute();
   

3. 建立新的 Floodlight 活動，並指派剛建立的 Floodlight 活動群組 ID 以及所有其他必填欄位。

   // Set floodlight activity structure.
   FloodlightActivity activity = new FloodlightActivity();
   activity.setName(activityName);
   activity.setCountingMethod("STANDARD_COUNTING");
   activity.setExpectedUrl(url);
   activity.setFloodlightActivityGroupId(activityGroupId);
   activity.setFloodlightTagType("GLOBAL_SITE_TAG");
   

4. 呼叫 floodlightActivities.insert() 即可儲存新活動，以便傳回新活動的 ID。

   // Create the floodlight tag activity.
   FloodlightActivity result =
       reporting.floodlightActivities().insert(profileId, activity).execute();
   

5. 使用新活動的 floodlightActivityId 呼叫 floodlightActivities.generatetag() 來產生標記。將代碼傳送給廣告客戶網站的網站管理員。

   // Generate the floodlight activity tag.
   Generatetag request = reporting.floodlightActivities().generatetag(profileId);
   request.setFloodlightActivityId(activityId);
   
   FloodlightActivitiesGenerateTagResponse response = request.execute();
   

PHP

1. 建立新的 Floodlight 活動群組，傳入 name、type 和 floodlightConfigurationId 的值。

   $group = new Google_Service_Dfareporting_FloodlightActivityGroup();
   $group->setFloodlightConfigurationId($values['configuration_id']);
   $group->setName($values['group_name']);
   $group->setType('COUNTER');
   

2. 呼叫 floodlightActivityGroups.insert() 以儲存 Floodlight 活動群組，呼叫會傳回新群組的 ID。

   $result = $this->service->floodlightActivityGroups->insert(
       $values['user_profile_id'],
       $group
   );
   

3. 建立新的 Floodlight 活動，並指派剛建立的 Floodlight 活動群組 ID 以及所有其他必填欄位。

   $activity = new Google_Service_Dfareporting_FloodlightActivity();
   $activity->setCountingMethod('STANDARD_COUNTING');
   $activity->setExpectedUrl($values['url']);
   $activity->setFloodlightActivityGroupId($values['activity_group_id']);
   $activity->setFloodlightTagType('GLOBAL_SITE_TAG');
   $activity->setName($values['activity_name']);
   

4. 呼叫 floodlightActivities.insert() 即可儲存新活動，以便傳回新活動的 ID。

   $result = $this->service->floodlightActivities->insert(
       $values['user_profile_id'],
       $activity
   );
   

5. 使用新活動的 floodlightActivityId 呼叫 floodlightActivities.generatetag() 來產生標記。將代碼傳送給廣告客戶網站的網站管理員。

   $result = $this->service->floodlightActivities->generatetag(
       $values['user_profile_id'],
       ['floodlightActivityId' => $values['activity_id']]
   );
   

Python

1. 建立新的 Floodlight 活動群組，傳入 name、type 和 floodlightConfigurationId 的值。

   # Construct and save floodlight activity group.
   activity_group = {
       'name': 'Test Floodlight Activity Group',
       'floodlightConfigurationId': floodlight_config_id,
       'type': 'COUNTER'
   }
   

2. 呼叫 floodlightActivityGroups.insert() 以儲存 Floodlight 活動群組，呼叫會傳回新群組的 ID。

   request = service.floodlightActivityGroups().insert(
       profileId=profile_id, body=activity_group)
   

3. 建立新的 Floodlight 活動，並指派剛建立的 Floodlight 活動群組 ID 以及所有其他必填欄位。

   # Construct and save floodlight activity.
   floodlight_activity = {
       'countingMethod': 'STANDARD_COUNTING',
       'expectedUrl': 'http://www.google.com',
       'floodlightActivityGroupId': activity_group_id,
       'floodlightTagType': 'GLOBAL_SITE_TAG',
       'name': 'Test Floodlight Activity'
   }
   

4. 呼叫 floodlightActivities.insert() 即可儲存新活動，以便傳回新活動的 ID。

   request = service.floodlightActivities().insert(
       profileId=profile_id, body=floodlight_activity)
   

5. 使用新活動的 floodlightActivityId 呼叫 floodlightActivities.generatetag() 來產生標記。將代碼傳送給廣告客戶網站的網站管理員。

   # Construct the request.
   request = service.floodlightActivities().generatetag(
       profileId=profile_id, floodlightActivityId=activity_id)
   
   # Execute request and print response.
   response = request.execute()
   

Ruby

1. 建立新的 Floodlight 活動群組，傳入 name、type 和 floodlightConfigurationId 的值。

   # Create a new floodlight activity group resource to insert.
   activity_group =
     DfareportingUtils::API_NAMESPACE::FloodlightActivityGroup.new(
       floodlight_configuration_id: floodlight_config_id,
       name:
         format('Example Floodlight Activity Group #%s', SecureRandom.hex(3)),
       type: 'COUNTER'
     )
   

2. 呼叫 floodlightActivityGroups.insert() 以儲存 Floodlight 活動群組，呼叫會傳回新群組的 ID。

   # Insert the floodlight activity group.
   result = service.insert_floodlight_activity_group(profile_id, activity_group)
   

3. 建立新的 Floodlight 活動，並指派剛建立的 Floodlight 活動群組 ID 以及所有其他必填欄位。

   # Create a new floodlight activity resource to insert.
   activity = DfareportingUtils::API_NAMESPACE::FloodlightActivity.new(
     counting_method: 'STANDARD_COUNTING',
     expected_url: 'http://www.google.com',
     floodlight_activity_group_id: activity_group_id,
     floodlight_tag_type: 'GLOBAL_SITE_TAG',
     name: format('Example Floodlight Activity #%s', SecureRandom.hex(3))
   )
   

4. 呼叫 floodlightActivities.insert() 即可儲存新活動，以便傳回新活動的 ID。

   # Insert the floodlight activity.
   result = service.insert_floodlight_activity(profile_id, activity)
   

5. 使用新活動的 floodlightActivityId 呼叫 floodlightActivities.generatetag() 來產生標記。將代碼傳送給廣告客戶網站的網站管理員。

   # Construct the request.
   result = service.generatetag_floodlight_activity(profile_id,
     floodlight_activity_id: activity_id)
   

產生刊登位置代碼

最後一個步驟是產生 HTML 代碼並傳送給發布商，以便顯示廣告。如要透過 API 產生標記，請向 placements.generatetags() 發出要求，指定一組 placementIds 和 tagFormats。

C#

// Generate the placement activity tags.
PlacementsResource.GeneratetagsRequest request =
    service.Placements.Generatetags(profileId);
request.CampaignId = campaignId;
request.TagFormats =
    PlacementsResource.GeneratetagsRequest.TagFormatsEnum.PLACEMENTTAGIFRAMEJAVASCRIPT;
request.PlacementIds = placementId.ToString();

PlacementsGenerateTagsResponse response = request.Execute();

Java

// Generate the placement activity tags.
Generatetags request = reporting.placements().generatetags(profileId);
request.setCampaignId(campaignId);
request.setTagFormats(tagFormats);
request.setPlacementIds(ImmutableList.of(placementId));

PlacementsGenerateTagsResponse response = request.execute();

PHP

$placementTags = $this->service->placements->generatetags(
    $values['user_profile_id'],
    ['campaignId' => $values['campaign_id'],
     'placementIds' => [$values['placement_id']],
     'tagFormats' => ['PLACEMENT_TAG_STANDARD',
                      'PLACEMENT_TAG_IFRAME_JAVASCRIPT',
                      'PLACEMENT_TAG_INTERNAL_REDIRECT']
    ]
);

Python

# Construct the request.
request = service.placements().generatetags(
    profileId=profile_id, campaignId=campaign_id,
    placementIds=[placement_id])

# Execute request and print response.
response = request.execute()

Ruby

# Construct the request.
result = service.generate_placement_tags(profile_id,
  campaign_id: campaign_id,
  placement_ids: [placement_id])