上位互換性マップ

forwardCompatibilityMap フィールドを使用すると、API で正式に公開される前の新しい機能を試すことができます。このフィールドは主要な API エンティティ(Campaign など)に含まれています。

String_StringMapEntry タイプの forwardCompatibilityMap は文字列と文字列の対応を表すもので、API エンティティのプロパティ(オブジェクトやその派生要素の正式な属性としてまだ公開されていないもの)を取得、設定するために使います。そうしたプロパティは forwardCompatibilityMap のキーを通じて公開されます。forwardCompatibilityMap フィールドを持つオブジェクトには CampaignAdGroupAdGroupAd があります。

マップを参照する

forwardCompatibilityMap フィールドを Selector.fields 配列の一部として参照する必要はありません。API のご利用のバージョンやサービスで少なくとも 1 つのキーが公開されていれば、forwardCompatibilityMap フィールドはレスポンスに含まれています。

マップにはオブジェクト タイプに応じた一連のキーが含まれ、オブジェクトやその派生要素の正式な属性の拡張機能として公開されます。オブジェクトの forwardCompatibilityMap に含まれるキーは、そのオブジェクトの属性ではなく派生要素の属性を参照している場合もあります。たとえば AdGroupAd のマップには Ad.devicePreferred というキーがありますが、このキーは実際には Ad オブジェクト(AdGroupAd の派生要素)のものです。

マップの値は string 型になりますが、関連するキーやそのキーが表す属性によっては、それらの値は別の基本的なデータ型(integer や boolean など)を文字列で表したものになる場合があります。そうしたデータ型は、場合により使用前に変換する必要があります。

サンプルを確認する

次のコードサンプルは CampaignService の get() メソッドを呼び出して Campaign.enhanced から forwardCompatibilityMap キーを取得します。このサンプルは Java クライアント ライブラリを使って作成しました。

 // Get the CampaignService.
 CampaignServiceInterface campaignService =
     adWordsServices.get(session, CampaignServiceInterface.class);

 // Create selector.
 Selector selector = new Selector();
 // Set the selector fields.
 // Notice there is no need to explicitly request the
 // forwardCompatibilityMap, indeed adding to the list of fields
 // will throw an error.
 selector.setFields(new String[] {"Id", "Name"});

 CampaignPage page = campaignService.get(selector);

 // Display campaigns.
 if (page.getEntries() != null) {
   for (Campaign campaign : page.getEntries()) {
     Map forwardCompatibilityMap =
         Maps.toMap(campaign.getForwardCompatibilityMap());
     System.out.println(String.format(
         "Campaign ID %d has enhanced value of '%s'",
         campaign.getId(),
         forwardCompatibilityMap.get("Campaign.enhanced")));
   }
 } else {
   System.out.println("No campaigns were found.");
 }

マップのプロパティを変更する

forwardCompatibilityMap を使って Campaign.enhanced などのキーを変更する方法は、他の属性の場合と同じです。変更を加えるキーと値を forwardCompatibilityMap に設定して、mutate() メソッドを呼び出してください。通常の mutate オペレーション ADDSETforwardCompatibilityMap のデータを受け入れますが、次の点に注意してください。

キーに有効な値を指定しないと、ApiException が送出されます。また、キーの名前を間違えないようにすることも重要です。名前が不正確か未定義のキーは暗黙的に無視されるため、エラーの診断が難しくなります。

コードのサンプル

次のサンプルでは forwardCompatibilityMaptrue にして Campaign.enhanced キーを渡し、キャンペーンをエンハンスト キャンペーンに変更します。このサンプルは Java クライアント ライブラリを使って作成しました。

// This is an example on how to enhance a campaign using the
// CampaignService and the forwardCompatibilityMap field.

// Get the CampaignService.
CampaignServiceInterface campaignService =
    adWordsServices.get(session, CampaignServiceInterface.class);

// Create campaign with updated status.
Campaign campaign = new Campaign();
campaign.setId(campaignId);
// Set the "Campaign.enhanced" as "true" to update the campaign.
campaign.setForwardCompatibilityMap(new String_StringMapEntry[] {
    new String_StringMapEntry("Campaign.enhanced",
        Boolean.TRUE.toString())});

// Create operations.
CampaignOperation operation = new CampaignOperation();
operation.setOperand(campaign);
operation.setOperator(Operator.SET);

CampaignOperation[] operations =
    new CampaignOperation[] {operation};

// Update campaign.
CampaignReturnValue result = campaignService.mutate(operations);

エラー処理

オペレーションで forwardCompatibilityMap のキーとして無効なを渡した場合は、ApiError を含む ApiException が送出されます。このエラーには forwardCompatibilityMap を指す fieldPath と問題の値が入った trigger が含まれます。

無効なキー名を渡すと API で暗黙的に無視されるため、エラーの原因を調べることが難しくなります。

また、キーは API のバージョンに依存しますのでご注意ください。あるバージョンで有効だったキーでも、その機能が正式に導入されたバージョンでは使えなくなります。新しい API バージョンに、すでに使えなくなったキーを渡すと ApiException が返されます。

よくある質問

レスポンスに入力する forwardCompatibilityMap をリクエストする方法を教えてください。ドキュメントには該当するフィールド名が見当たりません。

このフィールドを Selector.fields でリクエストする必要はありません。マップで返されるオブジェクトにデータがあった場合に、自動的に入力されます。

forwardCompatibilityMap にデータが入力されないのはなぜですか?

一般的には、そのオブジェクトにマップのキーに関するデータがないためです。

マップに間違ったキーを送るとエラーになりますか?

いいえ。API は認識できないキーを暗黙的に無視するため、キー名を指定する際には間違えないようご注意ください。

オブジェクトに新しいフィールドやキーはありますが、forwardCompatibilityMap は見当たりません。

forwardCompatibilityMap は、API の上位レベルのエンティティ(CampaignAdGroupAdGroupAd など)でのみ公開されます。ただし、一部のキーは下位レベルのオブジェクトにも影響します。

マップに間違った値を送るとどうなりますか?

正しいキーを設定したうえで非対応の値を使うと、ApiException が返されます。

キーは API のすべてのバージョンで公開されますか?

いいえ。キーはその機能がまだ公開されていない API バージョンでのみ公開され、使用できます。

フィードバックを送信...

ご不明な点がありましたら、Google のサポートページをご覧ください。