v1beta から v1 に移行する

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

主な違い

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

• Merchant API を使用するための 1 回限りの API デベロッパーの登録（1 人以上）: 連絡先情報を登録するには、registerGcp メソッドを呼び出す必要があります（認証に使用する Google Cloud プロジェクトごとに 1 回のみ）。これにより、API を使用して、Merchant API に関連する最新情報やお知らせを受け取ることができます。この手順が完了するまで、v1 API または v1alpha API を使用することはできません。手順については、デベロッパーとして登録するをご覧ください。
• 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 フィールドは移行を支援するための補助フィールドであり、オンラインとローカルのマーケティング方法を単一の商品ソースで完全にターゲットにできるようになれば、最終的に非推奨となります。詳しくは、次のセクションの表をご覧ください。
• 地域別在庫とローカル在庫の属性の新しいフィールド:
  • 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、またはクライアント ライブラリの使用）に関係なく、段階的に移行できます。つまり、統合全体を一度に更新する必要はなく、コードを API ごとに更新して移行できます（たとえば、Accounts API を v1beta に残したまま、Products API を v1 に移動するなど）。

フィールドの変更の詳細

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

v1beta	v1	説明
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 フィールドを使用して、アカウントに最初の管理者を追加します。