バージョン 13 への移行

  • [アーティクル]

注:

Bing Ads API バージョン 12 sunset sunset (2019 年 10 月 31 日時点)。

以下のセクションでは、Bing Ads API のバージョン 12 からバージョン 13 への変更について説明します。

すべてのサービスの認証

開発者向けの Microsoft ID プラットフォーム エンドポイント が利用可能になりました。 Microsoft ID プラットフォーム エンドポイントを使用すると、Azure AD の職場または学校アカウントと、hotmail.com、outlook.com、msn.com などの個人用 Microsoft アカウント (MSA) の両方を使用できます。 Live Connect エンドポイントでは、個人アカウントでの認証のみが許可されます。

Live Connect エンドポイントから Microsoft ID プラットフォーム エンドポイント への移行は、バージョン 12 から 13 への移行とは無関係ですが、多くの開発者が同じスプリント中にアップグレードすることを望んでいることは理解しています。

重要

Live Connect エンドポイントは、Microsoft Advertising ユーザーに推奨されるアプローチではなくなりました。 Microsoft ID プラットフォーム エンドポイントにアップグレードして、アプリケーションがサービスの摩擦や中断なしにすべてのユーザーをサポートできるようにします。 microsoft ID プラットフォーム エンドポイント (v2.0) のみが、Bing Ads API を介して職場アカウントと個人アカウントの両方を認証するためのアクセス トークンを取得できます。

Ad Insight

包括的なバージョン 13 サービスリファレンスドキュメントについては、 Ad Insight に関するページを参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/AdInsight/v13。

運用エンドポイントが https://adinsight.api.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc。

サンドボックス エンドポイントは https://adinsight.api.sandbox.bingads.microsoft.com/Api/Advertiser/AdInsight/v13/AdInsightService.svc です。

データ コントラクト名前空間

以前のバージョン 12 では、一部のエンティティのデータ コントラクト名前空間は、Ad Insight ターゲット名前空間とは異なっていました。 次のいずれかのバージョン 12 名前空間を使用した場合は、バージョン 13 で https://bingads.microsoft.com/AdInsight/v13 を使用する必要があります。

  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.SearchParameters
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.Common
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity.Criterions
  • Microsoft.BingAds.Advertiser.AdInsight.Api.DataContract.V12.Entity

SOAP エンベロープをエンコードするクライアントe.g. PHP DateRangeSearchParameter のSoapVarをエンコードするクライアントは、Ad Insight Version 13 ターゲット名前空間 (https://bingads.microsoft.com/AdInsight/v13) に更新する必要があります。

Bing Ads Python SDK クライアントは 、SUDS クライアント ファクトリ オブジェクトに対していくつかの名前空間プレフィックスを更新する必要があります。たとえば、Bing Ads API バージョン 12 で ns4:DateRangeSearchParameter を 使用した場合は、バージョン 13 で DateRangeSearchParameter ('ns4' プレフィックスなし) を使用します。 名前空間プレフィックスを決定する方法の詳細については、「 SUDS の使用 」を参照してください。

バルク

包括的なバージョン 13 サービス リファレンス ドキュメントについては、「 一括」を参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/CampaignManagement/v13。

運用エンドポイントが https://bulk.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc。

サンドボックス エンドポイントが https://bulk.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/BulkService.svc。

レスポンシブ広告画像アセット

横長画像メディア ID、横長ロゴ メディア ID、正方形の画像メディア ID、および正方形のロゴ メディア ID 列は、 レスポンシブ広告 レコードから非推奨になりました。 ダウンロード ファイルには引き続き表示されますが、将来のバージョンでは削除されるため、これらの列に依存関係を設定しないでください。 代わりに[ イメージ ] 列を使用してください。

エンティティ パフォーマンス データ

パフォーマンス データの一括ダウンロードは、バージョン 12 で以前に終了しました。 バージョン 13 では、 DataScope 値セットの EntityPerformanceData 値がサービス コントラクトから削除されました。 また、 Date オブジェクトと PerformanceStatsDateRange オブジェクトと ReportTimePeriod 値セットは削除されます。日、週、または月で集計するデータを必要とする場合は、Reporting API を使用できます。 詳細については、「 Reporting API Guides」を参照してください。

キャンペーン管理

包括的なバージョン 13 サービスリファレンスドキュメントについては、「 キャンペーン管理」を参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/CampaignManagement/v13。

運用エンドポイントが https://campaign.api.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc。

サンドボックス エンドポイントが https://campaign.api.sandbox.bingads.microsoft.com/Api/Advertiser/CampaignManagement/v13/CampaignManagementService.svc。

レスポンシブ広告画像アセット

LandscapeImageMediaId、LandscapeLogoMediaId、SquareImageMediaId、SquareLogoMediaId の各要素は 、ResponsiveAd オブジェクトから削除されます。 代わりに Images 要素を使用する必要があります。

レスポンシブ広告テキストアセット

バージョン 12 で LongHeadline 文字列要素を使用した場合は、バージョン 13 で LongHeadlineString (string) 要素を使用する必要があります。 LongHeadline のデータ型は、文字列から AssetLink に更新されます。 この資産リンクは、今後使用するために予約されています。

広告 見出し と 説明 のアセット リンク リストは、今後使用するために追加されます。

GetMediaMetaDataByAccountId の既定のページング

GetMediaMetaDataByAccountId 操作を呼び出すときに PageInfo 要素が設定されていない場合、defaut ページのインデックスは 0 になり、既定の Size は 1,000 になります。 バージョン 12 で PageInfo が設定されていない場合、アカウント内のすべてのメディア メタデータが返されます。

無効なデータ型の基準入札が無視されました

BiddableCampaignCriterion を追加および更新する場合、バージョン 12 と 13 の両方で、派生する CriterionBid オブジェクトの種類の要件は、ペアになっている派生の Criterion オブジェクト型のコンテキストによって異なります。 たとえば、継承された 条件 が ProductScope 条件の場合は、 FixedBid オブジェクト ( BidMultiplier ではなく) を使用する必要があります。

バージョン 13 では、正しい Criterion オブジェクトを使用しない場合、要求された入札は無視されます。入札が必要な場合、操作は失敗します。入札が省略可能な場合は、既定の入札が使用されます。

バージョン 12 では、正しい Criterion オブジェクトを使用しない場合は、要求された入札が適用されます。ただし、オブジェクトを後で取得すると、正しい型が返されます。 つまり、設定したデータ型は、取得したデータ型と同じではありません。

バージョン 12 からバージョン 13 へのこの変更は、キャンペーン レベルの入札可能な条件にのみ適用されます。 バージョン 12 と 13 の両方の入札可能な広告グループの条件について、正しい Criterion オブジェクトを使用しない場合、要求された入札は無視されます。入札が必要な場合、操作は失敗します。入札が省略可能な場合は、既定の入札が使用されます。

省略可能なキーワードの入札

AddKeywords 操作を呼び出すと、Keyword の Bid 要素は省略可能です。 以前のバージョン 12 では、キーワードを追加するために入札が必要でした。 キーワードと一致の種類の既定の広告グループの入札を継承する場合は、キーワードの入札を空のままにすることができます。

負のキーワードの一致の種類

NegativeKeyword の MatchType 要素は nillable です。 以前にバージョン 12 の既定の MatchType 値 (Exact) に依存していた場合は、この必須要素をバージョン 13 で明示的に設定する必要があります。

動的検索広告ソース

DynamicSearchAdsSetting の Source 要素は、nillable です。 IncludeDynamicSearchAdsSource 要素は、AddCampaigns および UpdateCampaigns 要求メッセージから削除されます。 ページ フィードを有効にしている場合は、バージョン 13 で [ソース] を設定できます。

キャンペーンの説明

Description 要素が Campaign オブジェクトから削除されます。 引き続き Name 要素を使用して、一意のキャンペーン名を指定できます。

追加のフィールドを返す

ReturnAdditionalFields 要素が GetAdExtensionsAssociations から削除されます。 GetAdExtensionsByIds、GetAdGroupCriterionsByIds、GetAdGroupsByCampaignId、GetAdGroupsByIds、GetAdsByAdGroupId、GetAdsByEditorialStatus、GetAdsByIds、GetCampaignsByAccountIds、GetCampaignsByAdGroupId、GetKeywordsByAdGroupId、GetKeywordsByEditorialStatus、および GetKeywordsByIds 要求メッセージ。 既定では、各広告、広告拡張機能、広告グループ、入札可能な広告グループの条件、キャンペーン、キーワードのすべての要素が返されます。

関連する AdAdditionalField、AdExtensionAdditionalField、AdGroupAdditionalField、AdGroupCriterionAdditionalField、CampaignAdditionalField、KeywordAdditionalField の値セットが並列で削除されます。

ターゲット移行の完了

共有ターゲットから排他的キャンペーンと広告グループのターゲット条件への移行は、以前に完了しました。 IsMigrated 要素は、 AddAdGroupCriterions、 UpdateAdGroupCriterions、 AddCampaignCriterions、 UpdateCampaignCriterions 操作の応答から削除されるようになりました。

新機能

新しい入札戦略の種類

MaxRoasBiddingScheme と TargetRoasBiddingScheme 入札戦略の種類は、バージョン 13 で今後使用するために追加されます。

顧客共有

CustomerShare 要素が Audience オブジェクトと UetTag オブジェクトに 追加されます。 この要素は、将来使用するために予約されています。

コンバージョン目標 入札から除外

ExcludeFromBidding 要素が ConversionGoal オブジェクトに追加されます。 この要素は、将来使用するために予約されています。

顧客の請求

包括的なバージョン 13 サービス リファレンス ドキュメントについては、「 顧客の課金」を参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/Billing/v13。

運用エンドポイントが https://clientcenter.api.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc。

サンドボックス エンドポイントが https://clientcenter.api.sandbox.bingads.microsoft.com/Api/Billing/v13/CustomerBillingService.svc。

挿入順序オブジェクト

複数のプロパティが InsertionOrder オブジェクトに追加されます。

BalanceAmount 要素が削除され、BudgetRemaining 要素に置き換えられます。

GetInsertionOrdersByAccount が削除されました

GetInsertionOrdersByAccount 操作が削除されます。 バージョン 13 では SearchInsertionOrders を使用できます。

顧客管理

包括的なバージョン 13 サービス リファレンス ドキュメントについては、「 Customer Management」を参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/Customer/v13。

運用エンドポイントが https://clientcenter.api.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc。

サンドボックス エンドポイントが https://clientcenter.api.sandbox.bingads.microsoft.com/Api/CustomerManagement/v13/CustomerManagementService.svc。

ClientLink オブジェクトにいくつかの変更が加わります。

顧客住所

バージョン 13 では、CustomerAddress 要素は既定で返されるすべての Customer オブジェクトに含まれます。 この要素を明示的に要求する必要はありません。 IncludeCustomerAddress 要素は、GetCustomer および SearchCustomers 要求メッセージから削除されます。

リンクされたアカウント ID

バージョン 13 では、LinkedAccountIds 要素は、既定で返されるすべての CustomerRole オブジェクトに含まれます。 この要素を明示的に要求する必要はありません。 IncludeLinkedAccountIds 要素は、GetUser 要求メッセージから削除されます。

オーストラリアとブラジルの税務情報

オーストラリアとブラジルの TaxInformation アカウントを設定すると、TaxId キーと TaxType キーは使用できなくなります。 オーストラリアの場合は、キーとして AUGSTNumber を使用し、値を税識別子に設定します。 ブラジルの場合、使用可能なキーは CCM、CPF、および CNPJ です。

説明 Version 12 バージョン 13
オーストラリアのアカウント TaxId=YourTaxId AUGSTNumber=YourTaxId
ブラジルのビジネス アカウント TaxId=YourTaxId;TaxType=Business CPNJ=YourTaxId
ブラジルの個人アカウント TaxId=YourTaxId;TaxType=Personal CPF=YourTaxId

サンパウロ市内のビジネス アカウントの場合、ブラジルではバージョン 12 から 13 の間で CCM キーに変更はありません。

新機能

顧客ロール リンクのアクセス許可

CustomerLinkPermission 要素が CustomerRole オブジェクトに追加されます。 この要素は、将来使用するために予約されています。

Reporting

包括的なバージョン 13 サービス リファレンス ドキュメントについては、 レポートに関するページを参照してください。

破壊的変更

プロキシ クライアント

新しいエンドポイント アドレスと名前空間を使用するようにプロキシ クライアントを更新します。

ターゲット名前空間が https://bingads.microsoft.com/Reporting/v13。

運用エンドポイントが https://reporting.api.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc。

サンドボックス エンドポイントが https://reporting.api.sandbox.bingads.microsoft.com/Api/Advertiser/Reporting/v13/ReportingService.svc。

ProductMatchCountReportRequest に必要な列

ProductMatchCountReportRequest を送信すると、必要な列が更新されます。 バージョン 13 では、AccountName、CampaignName、MatchedProductsAtProductGroup、および ProductGroup 列が必要です。

以前のバージョン 12 では、AccountName と CampaignName の要件に加えて、MatchedProductsAtAdGroup、MatchedProductsAtCampaign、または MatchedProductsAtProductGroup のパフォーマンス統計列の 1 つ以上が必要でした。

言語レポート フィルター

LanguageReportFilter 値セットが追加されます。 LanguageCode (文字列) 要素は、次のレポート フィルターの Languages (LanguageReportFilter) 要素に置き換えられます。

目標のすべてのコンバージョンと収益レポート

GoalsAndFunnelsReportColumn の [コンバージョン] 列と [収益] 列の名前はそれぞれ AllConversions と AllRevenue に変更されます。 データの意味はバージョン 12 から 13 に変更されていません。

フランス語のレポート ヘッダー

フランス語のヘッダーを含むレポートのダウンロードのサポートは削除されます。 バージョン 13 では、英語のヘッダーのみがサポートされています。 Language 要素は ReportRequest オブジェクトから削除され、ReportLanguage 値セットは削除されます。

AgeGenderDemographicReportRequest を削除しました

AgeGenderDemographicReportRequest が削除されます。 代わりに、 AgeGenderAudienceReportRequest を使用できます。

検索キャンペーンの種類

検索キャンペーンの場合、 CampaignType 列内で返されるデータは "検索" です。 バージョン 12 では、返された値は "コンテンツ & 検索" でした。 CampaignType 列は、AdGroupPerformanceReportColumn、AdPerformanceReportColumn、CampaignPerformanceReportColumn、SearchQueryPerformanceReportColumn の値セットを使用して使用できます。

製品グループのデータ形式

ProductGroup 列で返されるデータの形式が更新されます。

バージョン 説明 例
12 "\" (下位スラッシュ) を使用してレベルを区切ります。

属性値は "" (二重引用符) で囲まれていません。

該当する場合は、カテゴリ レベルが属性値に追加されます (例: "(1st Level)"、"(2nd Level)"、etcetera)。		 * \ Category=Animals & ペット用品(第1レベル) \ Category=Pet supplies(2レベル) \ Category=Bird supplies(3レベル)
13 "/" (スラッシュ) を使用してレベルを区切ります。

属性値は"" (二重引用符) で囲まれています。

"(第 1 レベル)" が削除された場合など、カテゴリ レベルは示されません。		 * / Category="ペット用品 & 動物" / Category="ペット用品" / Category="Bird supplies"

この変更は、次の値セットを使用して ProductGroup 列に適用されます。

使用できない品質スコアのダッシュ

バージョン 13 で品質スコアが計算されなかった場合、返されるデータは、AdRelevance、ExpectedCtr、HistoricalAdRelevance、HistoricalExpectedCtr、HistoricalLandingPageExperience、HistoricalQualityScore、LandingPageExperience、QualityScore 列の "-" (二重ダッシュ) になります。 バージョン 12 では、"0" (ゼロ) の値が返されました。 これらの列は、 AdGroupPerformanceReportColumn、 CampaignPerformanceReportColumn、 KeywordPerformanceReportColumn、 ShareOfVoiceReportColumn の値セットで使用できます。

一部のインプレッション シェア列を置き換えた

ImpressionLostToAdRelevancePercent、ImpressionLostToBidPercent、ImpressionLostToExpectedCtrPercent、ImpressionLostToRelevancePercent、および ImpressionLostToRankPercent 列は、 AccountPerformanceReportColumn、 AdGroupPerformanceReportColumn、 CampaignPerformanceReportColumn、 ShareOfVoiceReportColumn の各値セットから削除されます。

バージョン 13 では、これらのバージョン 12 の列間で分割されたデータが集計され、ImpressionLostToRankAggPercent 列を介して使用できます。この列では、ランク率に失われたインプレッションを計算するときに、これらの要素をすべて考慮します。

AverageCpp、ClickCalls、ManualCalls 列を削除しました

AverageCpp、ClickCalls、ManualCalls の各列は、 AccountPerformanceReportColumn、 AdGroupPerformanceReportColumn 、 および CampaignPerformanceReportColumn の値セットから削除されます。

CallStatus 列と CallTypeName 列を削除しました

CallStatus 列と CallTypeName 列は、 CallDetailReportColumn 値セットから削除されます。 Microsoft Advertising は、2014 年 3 月 12 日に追跡された番号への手動通話の課金を停止しました。

アカウント、キャンペーン、広告グループのスコープを要求する

バージョン 13 では、要求を特定のアカウント、キャンペーン、または広告グループにスコープを設定する必要があります。 たとえば、 AccountThroughAdGroupReportScope を使用して、最大 1,000 個のアカウント、300 個のキャンペーン、または 300 個の広告グループを含めることができます。 以前のバージョン 12 では、一部のレポートの種類ではレポート スコープを null のままにしておくことができ、アクセスできるすべてのアカウントのデータが返されます。