製品の管理

コンテンツ API は、 製品 リソースを使用して Microsoft Merchant Center (MMC) ストアの製品オファリングを管理する RESTful API です。

Content API の呼び出しに使用するベース URI を次に示します。

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/

各 HTTP 要求には、ユーザーの OAuth アクセス トークンと開発者トークンが含まれている必要があります。 ユーザーのアクセス トークンを指定するには、 AuthenticationToken ヘッダーを設定します。 開発者トークンを指定するには、 DeveloperToken ヘッダーを設定します。

他の顧客に代わってカタログを管理する場合は、次の設定を行う必要があります。

• 管理しているストアを持つ顧客の顧客 ID に対する CustomerId ヘッダー。
• 管理する顧客のアカウントのアカウント ID に対する CustomerAccountId ヘッダー (管理対象アカウントは関係ありません)。

既定では、Content API は JSON オブジェクトを使用して製品オファーを表します。 XML を使用するには、 alt クエリ パラメーターを XML に設定します。

Products リソースの使用の詳細については、次のセクションを参照してください。

• ストアから製品オファーを取得する
• ストアから製品オファーの一覧を取得する
• ストアからのオファーの削除
• 製品オファーの追加と更新
• バッチ処理の使用

ストアから製品オファーを取得する

ストアから特定の製品オファーを取得するには、次のテンプレートをベース URI に追加します。

{mmcMerchantId}/products/{productUniqueId}

MMC ストア ID に設定{mmcMerchantId}し、製品の offerId ではなく完全修飾製品 ID (Online:en:US:Sku123 など) に設定{productUniqueId}します。 製品 ID では大文字と小文字が区別されるため、製品を追加したときに API から返された ID を使用します。

結果の URL に HTTP GET 要求を送信します。 製品が見つかった場合、応答にはオファーを含む Product オブジェクトが含まれます。

同じ ID を持つ製品を複数のカタログに挿入した場合、サービスから返されるのはそのうちの 1 つだけです。どの製品からどのカタログが決定されていないかを返します。 このため、同じ製品 ID を持つ製品を複数のカタログに挿入しないでください。

製品オファーを取得する方法を示すコード例については、「 製品の管理コード例」を参照してください。

ストアから製品オファーの一覧を取得する

ストアにある製品オファーの一覧を取得するには、次のテンプレートをベース URI に追加します。

{mmcMerchantId}/products

MMC ストア ID に設定 {mmcMerchantId} します。

オファーの一覧を表示するには、 max-results クエリ パラメーターと start-token クエリ パラメーターを使用します。 最初の呼び出しで、サービスが返すオファーの最大数に設定 max-results します。 サービスが返すことができるオファーの最大数は 250 です。 既定値は 25 です。 結果の URL に HTTP GET 要求を送信します。 要求の例を次に示します。

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250

ストアにオファーが含まれている場合、応答には、要求されたオファーの数までを含む Product オブジェクトが含まれます。

利用可能なオファーがさらにある場合、応答にはフィールドが nextPageToken 含まれます ( 「製品」を参照)。 nextPageTokenフィールドには、次の List 要求で パラメーターを に設定start-tokenするために使用するトークン値が含まれています。 トークンを使用する例を次に示します。

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?max-results=250&start-token=DFSos893j...

製品オファーの一覧を取得する方法を示すコード例については、「 製品の管理コード例」を参照してください。

ストアからのオファーの削除

ストアから特定の製品オファーを削除するには、次のテンプレートをベース URI に追加します。

{mmcMerchantId}/products/{productUniqueId}

MMC ストア ID に設定{mmcMerchantId}し、製品の offerId ではなく完全修飾製品 ID (Online:en:US:Sku123 など) に設定{productUniqueId}します。 製品 ID では大文字と小文字が区別されるため、製品を追加したときに API から返された ID を使用します。

結果の URL に HTTP DELETE 要求を送信します。 製品が見つかった場合は削除されます。

同じ製品 ID を持つ製品を複数のカタログに挿入した場合、サービスはそれらすべてを削除します。 同じ製品 ID を持つ製品を複数のカタログに挿入しないでください。

製品オファーを削除する方法を示すコード例については、「 製品の管理コード例」を参照してください。

製品オファーの追加と更新

オファーの追加または更新は、挿入操作です。 更新は挿入操作であるため、要求にオファーのすべてのフィールドを含める必要があります。1 つのフィールドを更新することはできません。

製品オファーを挿入するには、次のテンプレートをベース URI に追加します。

{mmcMerchantId}/products

MMC ストア ID に設定 {mmcMerchantId} します。

結果の URL に HTTP POST 要求を送信すると、オファーが既定のストア カタログに書き込まれます。 オファーを特定のカタログに書き込むには、 bmc-catalog-id クエリ パラメーターを含めます。

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products?bmc-catalog-id=123456

製品が挿入された場合、応答には Product オブジェクトが含まれます。 Productオブジェクトには、オファーの取得と削除に使用する製品 ID が含まれています。

オファーには、次のフィールドを含める必要があります。

• 可用性
• channel
• condition
• contentLanguage
• imageLink
• link
• offerId
• 価格
• targetCountry
• title

API では、 channel、 contentLanguage、 targetCountry、 offerId を使用して製品 ID を生成します。 これらのフィールドは ID の生成に使用されるため、更新することはできません。 製品 ID では大文字と小文字が区別されます。ID では、および を指定channelcontentLanguagetargetCountryするために使用したのと同じ大文字と小文字が使用されます。offerId

注意

大文字と小文字channelcontentLanguagetargetCountryが異なる場合は、同じ製品を効果的に複数回追加できるため、、 には同じ大文字とofferId小文字を使用してください。

製造元に値が割り当てられている場合は、次のフィールドも必要です。

• ブランド
• gtin
• Mpn

既知の場合は、値を指定する必要があります。 いずれも指定しない場合は、 identifierExists フィールドを false に設定する必要があります。 The default is true.

製品がこれらの識別子を持っていることがわかっていて、それらを指定していない場合、MMC は製品を今のところ受け入れますが Product 、応答のオブジェクトには フィールドが warnings 含まれます。 フィールドが存在するかどうかを常に warnings 確認し、特定されたすべての問題を修正する必要があります。

必須フィールドに加えて、オファーの有効期限を設定する日付と時刻も指定する必要があります ( 「expirationDate」を参照)。 既定では、オファーの有効期限は、ストアまたはカタログに書き込まれた日時から 30 日です。 有効期限が近い製品と有効期限が切れる前に、有効期限を更新するか、単に製品を更新する (製品のフィールドを更新する必要はありません) ことを追跡する必要があります。これにより、有効期限が 30 日に自動的に延長されます。 有効期限を明示的に設定する場合は、新しい有効期限を自分で設定する必要があります。この場合、製品を更新しても、自動的に有効期限が 30 日延長されることはありません。

その他のすべてのフィールドは省略可能と見なされます。ただし、製品を正確に記述するために必要な数を指定する必要があります。

注:

オブジェクトには Product 、値に設定されているフィールドのみを含める必要があります。 オブジェクトに null フィールドを Product 含めないでください。 たとえば、 は含 "adult":nullめないでください。

Microsoft では、すべてのフィールドを Product 使用しているわけではありません。 API が受け入れるが使用しないフィールドの一覧については、「 使用できる Google 属性 」を参照してください。Microsoft が使用するその他のすべてのフィールドは、製品広告の配信時に製品をフィルター処理するために使用されます。

Content API に不明なフィールドを指定した場合、サービスはそのフィールドを無視します。

オファーを挿入すると、サービスはオファーに対して基本的な検証を実行し、必要に応じてエラーと警告を返します。 エラーが発生した場合、応答には オブジェクトが ErrorResponse 含まれます。 警告が発生した場合、応答には オブジェクトが Product 含まれており、フィールドに warnings 警告が一覧表示されます。

オファーが基本的な検証に合格した場合、編集レビューなどのオフライン検証とレビューが行われ、最大 36 時間かかることがあります。 すべての検証とレビューが完了するまで、オファーは提供されません。 オファーの状態を確認するには、 Status リソースを使用します。

API では、ETags などのコンカレンシー コントロールは提供されないことに注意してください。 2 つのアプリが同じ製品を追加または更新しようとしている場合、最後のアプリが優先されます。

製品広告に表示されるオファーには、価格、タイトル、ストア名 (指定した場合は sellerName)、製品に関する詳細情報を含む Web ページへのリンク、製品の画像が含まれます。

複数の色、パターン、または素材で使用できるアパレル製品の場合は、バリエーションごとに製品を作成し、 itemGroupId フィールドを使用してすべての製品バリアントをグループ化します。

製品オファーを挿入する方法を示すコード例については、「製品の 管理コード例」を参照してください。

バッチ処理の使用

複数の製品オファーを処理する場合は、API のバッチ処理機能の使用を検討する必要があります。 この機能を使用すると、1 つの要求で複数の挿入、取得、削除を処理できます。 同じ要求で複数のオファーを処理する方が、オファーごとに個別の要求を送信するよりも効率的です。 1 つの要求の処理に伴うコストは、個々の要求ごとにそのコストが発生するのではなく、バッチ要求内の数千のオファーに分散されます。

同じ要求で同じ製品を挿入、取得、または削除しないでください。

バッチ要求を送信するには、次のテンプレートをベース URI に追加します。

{mmcMerchantId}/products/batch

MMC ストア ID に設定 {mmcMerchantId} します。

結果の URL に HTTP POST 要求を送信すると、挿入操作が既定のストア カタログに適用されます。 オファーを特定のカタログに適用するには、 bmc-catalog-id クエリ パラメーターを含めます。

https://content.api.bingads.microsoft.com/shopping/v9.1/bmc/{mmcMerchantId}/products/batch?bmc-catalog-id=123456

POST の本文は、Item オブジェクトの配列を含む Batch オブジェクトです。 すべての操作で、、および フィールドをbatchIdmerchantIdmethod設定します。 batchIdは、応答のバッチ項目を識別するために使用するユーザー定義 ID です。はmerchantIdストア ID method であり、 は実行する操作です (挿入、削除、取得など)。

が insert の場合methodは、追加または更新するオファーを含む Product オブジェクトにフィールドを設定productします。 それ以外の場合は、取得または削除の場合methodは、取得または削除するオファーの完全修飾 ID に設定productIdします。

バッチ要求の本文のサイズは、4 MB を超えることはできません。 本文が 4 MB を超える場合、応答は HTTP 状態コード 413 を返します。 各オファーのサイズ (指定したフィールドの数) に応じて、2,000 ~ 6,000 個のオファーを送信できます。 本文を圧縮すると、オファーの最大数 (サイズに応じて) 12,000 個を送信できます。

本文を圧縮するには、GZip 圧縮のみを使用し、要求の Content-Encoding ヘッダーを gzip に設定します。

サービスは、バッチ内の各項目を処理します。 応答には、要求に Batch 含まれる各 Item オブジェクトが含まれています。 応答内の項目の順序が要求の項目と同じ順序である保証はありません。

挿入操作の場合、項目には と product フィールドのみがbatchId含まれます。 フィールド product には、要求で送信したオファーと同じオファーが含まれますが、完全修飾製品 ID も含まれています。 エラーまたは警告が発生した場合、項目には、、method、および error フィールドがbatchId含まれます。 この error フィールドには、挿入が失敗した理由や、修正する必要があるオファーの問題に関する警告が含まれています。

取得操作の場合、項目には と product フィールドがbatchId含まれます。 フィールド product には、要求したオファーが含まれます。 製品が見つからない場合、オブジェクトにはフィールドは product 含まれません。

削除操作の場合、アイテムにはフィールドのみが batchId 含まれます。オファーが存在し、削除されたかどうかを示す情報はありません。

バッチ処理の使用方法を示すコード例については、「 バッチ要求の作成」を参照してください。