v1beta から v1 に移行する

このガイドでは、Merchant API v1beta から一般提供の最初のバージョンである v1 への移行について説明します。v1 バージョンでは、いくつかの更新と、コードの更新が必要になる可能性のある変更が導入されています。これらの変更は、API を簡素化し、Merchant Center アカウントの管理を改善することを目的としています。

主な違い

v1beta から v1 に移行する際に注意すべき最も重要な変更点は次のとおりです。

  • Merchant API を使用するための API デベロッパーの 1 回限りの登録: 連絡先情報を登録するには、registerGcp メソッドを呼び出す必要があります（認証に使用する Google Cloud プロジェクトごとに 1 回のみ）。これにより、API を使用し、Merchant API に関連する最新情報やお知らせを受け取ることができます。この手順が完了するまで、v1 API または v1alpha API を使用することはできません。手順については、デベロッパーとして登録するをご覧ください。

  • 商品名のエンコード: ProductInput.name フィールドと Product.name フィールドは、パディングなしの base64url（RFC 4648 セクション 5）エンコードをサポートしています。次のガイドラインに沿って対応してください。

    • エンコードする前に、文字列は contentLanguage~feedLabel~offerId 形式に準拠している必要があります。

    • 商品名に Merchant API で使用される文字や URL 予約文字（次のような文字）が含まれている場合は、エンコードが必須です。

      % . + / : ~ , ( * ! ) & ? = @ # $

    • 商品名が contentLanguage~feedLabel~offerId 形式に準拠しており、Merchant API で使用される文字や URL 予約文字を含んでいない場合は、エンコードせずにプレーン形式を使用できます。

    • 一貫性のある正しい解析を保証するため、すべてのプロダクト名にパディングなしの base64url エンコードを使用することをおすすめします。

  • 商品単位の税金情報の削除: taxes と taxCategory。

  • Product.attributes の名前が変更されました: Product.attributes フィールドの名前が Product.productAttributes に変更されました。

  • 商品レベルの税情報の削除: taxes フィールドと taxCategory フィールドが Product.productAttributes オブジェクトから削除されました。詳しくは、税金に関する Google Merchant Center のヘルプ記事をご覧ください。

  • GTIN フィールドの変更: Product.productAttributes オブジェクトの gtin フィールドの名前が gtins に変更されました。これは、複数の値を保持できることを反映するためです。OrderTrackingSignals.lineItemDetails オブジェクトの gtin フィールドが array になり、gtins に名前変更されました。

  • チャネル フィールドの削除: channel フィールドが商品、商品入力、データソースから削除されました。実店舗でのみ販売される商品を明確に指定するために、新しいブール値フィールド legacyLocal が導入されました。注: legacyLocal フィールドは移行を支援するための補助フィールドであり、オンラインとローカルのマーケティング方法を 1 つの商品ソースで完全にターゲットにできるようになれば、最終的に非推奨となります。詳細については、次のセクションの表をご覧ください。

  • 地域とローカルの在庫属性の新しいフィールド:

    • name、account、region を除くすべての RegionalInventory フィールドが、regionalInventoryAttributes という新しいオブジェクトにラップされるようになりました。たとえば、RegionalInventory.price 属性は RegionalInventory.regionalInventoryAttributes.price になりました。
    • name、account、storeCode を除くすべての LocalInventory フィールドが、localInventoryAttributes という新しいオブジェクトにラップされるようになりました。たとえば、LocalInventory.price 属性は LocalInventory.localInventoryAttributes.price になりました。

  • 地域とローカルの在庫から customAttributes を削除: customAttributes フィールドは、RegionalInventory リソースと LocalInventory リソースの両方から削除されました。

  • アカウント作成の改善: 冗長な users フィールドが CreateAndConfigureAccountRequest から削除されました。単数形の user フィールドを使用して、最初のユーザーを新しいアカウントに関連付けます。

  • 一部の属性タイプが文字列から列挙型に変更されました。Product リソースと Inventory リソース内の値の短いリストが定義されている一部のフィールドが、より適切なデータ検証のために string 型から enum 型に変更されました（たとえば、Product.ProductAttributes.condition フィールドは enum になりました）。

  • オンライン返品ポリシーの更新メソッドの削除: v1 で onlineReturnPolicy.update メソッドが削除されます。代わりに、onlineReturnPolicy.create メソッドを使用してオンライン返品ポリシーを作成します。

移行方法

Merchant API の v1beta バージョンは、2026 年 2 月 28 日に廃止される予定です。非推奨のスケジュールについて詳しくは、Merchant API バージョニング ガイドをご覧ください。

  • 移行の最初の手順は、デベロッパーの登録を 1 回行うことです（デベロッパーとして登録するを参照）。v1 メソッドが機能する前に、認証に使用する Google Cloud プロジェクトごとに registerGcp メソッドを呼び出す必要があります。

  • API の呼び出し方法（REST、gRPC、クライアント ライブラリの使用）に関係なく、段階的に移行できます。つまり、統合全体を一度に更新することなく、コードを 1 つの API ずつ更新して移行できます（たとえば、Accounts API を v1beta に残したまま、Products API を v1 に移動するなど）。

フィールドの変更の詳細

この表は、v1beta バージョンと v1 バージョンで変更されたフィールドの詳細な比較を示しています。

v1beta v1 説明
ProductInput.name ProductInput.name Unpadded base64url encoding は、Merchant API で使用される文字または URL 予約文字を含む商品名でサポートされ、必須です。
Product.name Product.name Unpadded base64url encoding は、Merchant API で使用される文字または URL 予約文字を含む商品名でサポートされ、必須です。
Product.gtin Product.gtins GTIN のフィールドの名前が変更されました。
Product.taxes 削除済み taxes フィールドが削除されました
Product.taxCategory 削除済み taxCategory フィールドが削除されました
Product.channel 削除済み channel フィールドが削除されました。ローカル ユースケースには legacyLocal フィールドを使用します。
Product.attributes Product.productAttributes attributes フィールドの名前が productAttributes に変更されました。
Product フィールドの availability、condition、gender、includedDestinations、excludedDestinations は strings（または strings の array）として表されます。 これらのフィールドは enums（または enums の array）になりました。 値の短いリストが定義されているフィールドが、string 型から enum に変更されました。
RegionalInventory の price、salePrice、salePriceEffectiveDate および availability 「RegionalInventory.regionalInventoryAttributes」に移動しました これらのフィールドは regionalInventoryAttributes に移動しました。
RegionalInventory.availability フィールドは string です RegionalInventory.regionalInventoryAttributes.availability は enums になりました Availability の型を string から enum に変更しました。
LocalInventory の price、salePrice、salePriceEffectiveDate、availability、quantity、pickupMethod、pickupSla、instoreProductLocation 「LocalInventory.localInventoryAttributes」に移動しました これらのフィールドは localInventoryAttributes に移動しました。
LocalInventory.availability フィールドは string です LocalInventory.localInventoryAttributes.availability は enums になりました Availability の型を string から enum に変更しました。
LocalInventory.customAttributes 削除済み ローカル在庫のカスタム属性はサポートされなくなりました。
RegionalInventory.customAttributes 削除済み 地域別在庫のカスタム属性はサポートされなくなりました。
ProductInput.channel 削除済み channel フィールドが削除されました。ローカル ユースケースには legacyLocal フィールドを使用します。
DataSource.channel 削除済み channel フィールドが削除されました。ローカル ユースケースには legacyLocal フィールドを使用します。
利用不可 ProductInput.legacyLocal 商品がローカル マーケティング手法のみを対象にできることを示す新しいブール値フィールド。商品リソース ID には「local~」という接頭辞が付きます。
利用不可 Product.legacyLocal 商品が実店舗でのみ販売され、オンラインで購入できないことを示す新しいブール値フィールド。
利用不可 DataSource.legacyLocal データソースに実店舗でのみ販売される商品が含まれていることを示す新しいブール値フィールド。
OrderTrackingSignals.LineItemDetails.gtin OrderTrackingSignals.LineItemDetails.gtins gtin フィールドの名前が gtins に変更され、文字列（文字列ではなく）の配列になりました。
CreateAndConfigureAccountRequest.users 削除済み users フィールドが削除されました。user フィールドを使用して、アカウントに最初の管理者を追加します。

前へ
Refactor code for concurrent requests
次へ
Overview