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 に変更されました。

  • 商品レベルの税務情報削除: Product.productAttributes オブジェクトから taxes フィールドと taxCategory フィールドが削除されました。詳しくは、税金に関する 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 Merchant API で使用される文字または URL 予約文字を含む商品名の場合、Unpadded base64url encoding はサポート対象で必須です。
Product.name Product.name Merchant API で使用される文字または URL 予約文字を含む商品名の場合、Unpadded base64url encoding はサポート対象で必須です。
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 フィールドを使用して、アカウントに最初の管理者を追加します。