Bid Manager API v1.1 から v2 に移行する

2022 年 3 月に、Bid Manager API のバージョン 2 をリリースしました。この新しいバージョンのリリースに伴い、v1.1 のサポート終了日を近日中に発表する予定です。できるだけ早く v1.1 から v2 への移行を開始することをおすすめします。

アプリケーションの移行

v1.1 から v2 への移行では、v2 を呼び出すようにエンドポイント URL を更新し、破壊的変更に対応するようにアプリケーションを更新する必要があります。

API 呼び出しを v1.1 から v2 に更新する

v1.1 の代わりに v2 を使用するには、新しい v2 エンドポイントを使用するようにリクエストを更新する必要があります。

同等のメソッドを特定する

API 呼び出しを v1.1 から v2 に更新するには、まず v2 で同等の v1.1 メソッドを特定する必要があります。

v1.1 と v2 では、すべてのサービスとメソッドの名前が次のように若干変更されています。

• v1.1 のサービス Queries と Reports は、v2 では queries と queries.reports になっています。
• v2 では、メソッドの名前が次のように変更されています。

  v1.1 のメソッド名	同等の v2 メソッド
  Queries.createquery	queries.create
  Queries.deletequery	queries.delete
  Queries.getquery	queries.get
  Queries.listqueries	queries.list
  Queries.runquery	queries.run
  Reports.listreports	queries.reports.list

新しいエンドポイントに更新する

同等のメソッドを特定したら、リクエストを更新する必要があります。たとえば、v101.1 で queries.getquery メソッドを呼び出すには、次の URL を使用します。

https://www.googleapis.com/doubleclickbidmanager/v1.1/query/queryId

v2 で同等のメソッド（queries.get）を呼び出すには、 URL を次のように更新します。

GET https://doubleclickbidmanager.googleapis.com/v2/queries/queryId

クライアント ライブラリを使用して API にリクエストを行う場合は、クライアント ライブラリの最新バージョンを使用し、v2 を使用するように構成を更新します。

必要な変更を加える

v2 では、多くの破壊的変更が導入されています。以下の手順を確認し、既存の Bid Manager API の使用状況に応じて必要な変更を加えます。

queries サービスへの呼び出しを更新する

• Query リソースの次のフィールドは、元々一般的なネストされたオブジェクトで表されていましたが、次のオブジェクト タイプを使用するように変更されました。

  v1.1 のフィールド	同等の v2 オブジェクト タイプ
  metadata	QueryMetadata
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	削除済み
  params.options.pathQueryOptions.channelGrouping	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	削除済み
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	削除済み
  schedule	QuerySchedule

• Query リソースの次のフィールドは、元々一般的なリスト オブジェクトで表されていましたが、次の新しいオブジェクト タイプのリストに変更されました。

  v1.1 のリスト フィールド	v2 オブジェクト タイプ
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	削除済み
  params.options.pathQueryOptions.pathFilters[]	削除済み
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	削除済み

• Query リソースの次のフィールドは、元々文字列で表されていましたが、v2 では enum タイプで表されるようになり、次のような変更が加えられています。
  • metadata.dataRange に相当する v2 の値は、Range enum を使用するようになりました。この enum への変換では、値 PREVIOUS_HALF_MONTH が削除され、値 TYPE_NOT_SUPPORTED が RANGE_UNSPECIFIED に変更されました。
  • metadata.format は Format enum を使用するようになりました。この enum への変換では、値 EXCEL_CSV が削除され、値 FORMAT_UNSPECIFIED が追加されました。
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match と params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match はMatch enum を使用するようになりました。
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition は PathMatchPosition enum を使用するようになりました。この enum への変換では、値 PATH_MATCH_POSITION_UNSPECIFIED が追加されました。
  • schedule.frequency は Frequency enum を使用するようになりました。この enum への変換では、値 FREQUENCY_UNSPECIFIED が追加されました。
  • params.type は ReportType enum を使用するようになりました。この enum への変換では、次の変更が加えられました。
  • 次の値は非推奨になりました。
    • TYPE_ACTIVE_GRP
    • TYPE_AUDIENCE_PERFORMANCE
    • TYPE_CLIENT_SAFE
    • TYPE_COMSCORE_VCE
    • TYPE_CROSS_FEE
    • TYPE_CROSS_PARTNER
    • TYPE_CROSS_PARTNER_THIRD_PARTY_DATA_PROVIDER
    • TYPE_ESTIMATED_CONVERSION
    • TYPE_FEE
    • TYPE_KEYWORD
    • TYPE_LINEAR_TV_SEARCH_LIFT
    • TYPE_NIELSEN_AUDIENCE_PROFILE
    • TYPE_NIELSEN_DAILY_REACH_BUILD
    • TYPE_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PAGE_CATEGORY
    • TYPE_PETRA_NIELSEN_DAILY_REACH_BUILD
    • TYPE_PETRA_NIELSEN_ONLINE_GLOBAL_MARKET
    • TYPE_PIXEL_LOAD
    • TYPE_THIRD_PARTY_DATA_PROVIDER
    • TYPE_TRUEVIEW_IAR
    • TYPE_VERIFICATION
    • TYPE_YOUTUBE_VERTICAL
  • 残りの値はすべて、UI での同等の値をより適切に反映するように更新されました。

    v1.1 の値	同等の ReportType の値
    TYPE_NOT_SUPPORTED	REPORT_TYPE_UNSPECIFIED
    TYPE_GENERAL	STANDARD
    TYPE_INVENTORY_AVAILABILITY	INVENTORY_AVAILABILITY
    TYPE_AUDIENCE_COMPOSITION	AUDIENCE_COMPOSITION
    TYPE_ORDER_ID	FLOODLIGHT
    TYPE_TRUEVIEW	YOUTUBE
    TYPE_NIELSEN_SITE	GRP
    TYPE_PETRA_NIELSEN_AUDIENCE_PROFILE	YOUTUBE_PROGRAMMATIC_GUARANTEED
    TYPE_REACH_AND_FREQUENCY	REACH
    TYPE_REACH_AUDIENCE	UNIQUE_REACH_AUDIENCE
    TYPE_PATH	FULL_PATH
    TYPE_PATH_ATTRIBUTION	PATH_ATTRIBUTION

• フィールド metadata.dataRange、 reportDataStartTimeMs、 reportDataEndTimeMs は、フィールド range、customStartDate、 customEndDate に置き換えられました。新しい日付フィールドでは、Date オブジェクトではなく、Unix エポックからのミリ秒数が使用されます。これらの置き換えフィールド は、DataRange オブジェクトの QueryMetadata オブジェクトの dataRange フィールドに割り当てられました。
• フィールド schedule.startTimeMs と schedule.endTimeMs は、 QuerySchedule オブジェクトのフィールド startDate と endDate に置き換えられました。新しい日付フィールドでは、Date オブジェクトではなく、Unix エポックからのミリ秒数が使用されます。
• フィールド metadata.running、 metadata.reportCount、 metadata.googleCloudStoragePathForLatestReport、 metadata.googleDrivePathForLatestReport、および metadata.latestReportRunTimeMs は削除されました。 クエリで生成された最新のレポートに関する情報は、 queries.reports.list メソッドを orderBy クエリ パラメータを「key.reportId desc」に設定して使用する必要があります。これにより、リクエストで最新のレポートが最初に一覧表示されるようになります。
• フィールド kind、timezoneCode、 metadata.locale、 params.includeInviteData、および schedule.nextRunMinuteOfDay は削除されました。
• queries.create では、作成後にクエリが自動的に実行されなくなり、asynchronous クエリ パラメータが削除されました。新しいクエリのレポートを生成するには、queries.create の後に queries.run を呼び出します。
• queries.run メソッドは、次のように更新されました:
  • asynchronous クエリ パラメータが synchronous クエリ パラメータに置き換えられました。新しいクエリ パラメータは逆のロジックで動作し、指定されていない場合は false と見なされます。このため、queries.run は、v1.1 のデフォルトである同期処理とは異なり、v2 ではデフォルトでレポートを非同期で生成します。
  • リクエストの本文が更新され、 timezoneCode フィールドが削除され、 dataRange、reportDataStartTimeMs、 reportDataEndTimeMs フィールドが DataRange オブジェクトに割り当てられた dataRange フィールドに置き換えられました。
  • このメソッドは、空のレスポンス本文ではなく、結果の Report オブジェクトを返します。
• queries.list レスポンス本文 の kind フィールドが削除されました。

reports サービスへの呼び出しを更新する

• Report リソースの次のフィールドは、元々一般的なネストされたオブジェクトで表されていましたが、次のオブジェクト タイプを使用するように変更されました。

  v1.1 のフィールド	同等の v2 オブジェクト タイプ
  key	ReportKey
  metadata	ReportMetadata
  metadata.status	ReportStatus
  params	Parameters
  params.options	Options
  params.options.pathQueryOptions	削除済み
  params.options.pathQueryOptions.channelGrouping	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter	削除済み
  params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter	削除済み

• Report リソースの次のフィールドは、元々一般的なリスト オブジェクトで表されていましたが、次の新しいオブジェクト タイプのリストに変更されました。

  v1.1 のリスト フィールド	v2 オブジェクト タイプ
  params.filters[]	FilterPair
  params.options.pathQueryOptions.channelGrouping.rules[]	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[]	削除済み
  params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[]	削除済み
  params.options.pathQueryOptions.pathFilters[]	削除済み
  params.options.pathQueryOptions.pathFilters[].eventFilters[]	削除済み

• Report リソースの次のフィールドは、元々文字列で表されていましたが、v2 では同等のフィールドが新しい enum タイプで表されるようになり、許容される値が変更されています。
  • metadata.status.format は Format enum を使用するようになりました。この enum への変換では、値 EXCEL_CSV が削除され、FORMAT_UNSPECIFIED が追加されました。
  • metadata.status.state は State enum を使用するようになりました。この enum への変換では、値 QUEUED と STATE_UNSPECIFIED が追加されました。
  • params.options.pathQueryOptions.channelGrouping.rules[].disjunctiveMatchStatements[].eventFilters[].dimensionFilter.match と params.options.pathQueryOptions.pathFilters[].eventFilters[].dimensionFilter.match はMatch enum を使用するようになりました。
  • params.options.pathQueryOptions.pathFilters[].pathMatchPosition は PathMatchPosition enum を使用するようになりました。この enum への変換では、値 PATH_MATCH_POSITION_UNSPECIFIED が追加されました。
  • params.type は ReportType enum を使用するようになりました。この enum への変換では、多くの変更が加えられました。詳しくは、クエリ サービス呼び出しの更新に関する前のセクションをご覧ください。
• フィールド metadata.reportDataStartTimeMs と metadata.reportDataEndTimeMs は、 ReportMetadata オブジェクトの フィールド reportDataStartDate と reportDataEndDate に置き換えられました。新しいフィールドでは、Unix エポックからのミリ秒数ではなく Dateオブジェクトが使用されます。
• metadata.status.finishTimeMs は、 finishTime フィールドが ReportStatus オブジェクトに置き換えられました。この新しい時間フィールドは、Unix エポックからのミリ秒数ではなく、RFC3339 UTC Zulu 形式のタイムスタンプとして日時を表します。
• metadata.status.failure フィールドと params.includeInviteData フィールドは削除されました。
• kind フィールドが reports.list レスポンス本文から 削除されました。

エラー処理ロジックを更新する

API 全体でエラー メッセージが v2 で更新されました。これらの新しいエラー メッセージはより具体的になり、場合によっては、エラーが返される原因となっている API リクエストの値に関する情報が提供されます。既存のエラー処理ロジックが特定のエラー メッセージ テキストに依存している場合は、v2 に移行する前にエラー処理を一般化してください。