v1beta から v1 に移行する

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

主な違い

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

  • Merchant API を使用するための API デベロッパーの 1 回限りの登録: 連絡先情報を提供するには、registerGcp メソッドを呼び出す必要があります（認証に使用する Google Cloud プロジェクトごとに 1 回のみ）。これにより、API を使用し、Merchant API に関連する更新情報やお知らせを受け取ることができます。この手順が完了するまで、 v1 または 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 フィールドの変更: gtin フィールドは Product.productAttributes オブジェクトで gtins に名前が変更されました。これは、複数の値を保持できることを反映するためです。gtin フィールドが OrderTrackingSignals.lineItemDetails オブジェクトの array になり、gtins に名前が変更されました。

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

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

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

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

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

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

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

移行方法

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

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

  • API の呼び出し方法（REST、gRPC、クライアント ライブラリの使用）に関係なく、段階的に移行できます。つまり、統合全体を一度に更新しなくても、コードを 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（または array of strings）として表されます。 これらのフィールドが enums（または array of enums）になりました。 値の短いリストが定義されているフィールドが 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 フィールドを使用して、最初のアカウント管理者をアカウントに追加します。