このガイドでは、Content API for Shopping から Merchant API へのビジネスデータ管理の移行プロセスについて説明します。
このガイドでは、既存の Content API for Shopping の実装を Merchant API に移行する方法について説明します。Merchant API とそのサブ API の詳細については、Merchant API の設計をご覧ください。
始める
Merchant API の使用を開始するには、リクエスト URL を次の形式に変更します。
https://merchantapi.googleapis.com/{SUB_API}/{VERSION}/{RESOURCE_NAME}:{METHOD}…
Merchant API を使用するには、デベロッパー登録の方法を使用して、Merchant Center アカウントと Google Cloud プロジェクトを次のようにリンクする必要があります。
POST https://merchantapi.googleapis.com/accounts/v1/accounts/{ACCOUNT_ID}/developerRegistration:registerGcp
{
developer_email:"example-email@example.com"
}
詳しくは、クイック スタートガイドと Merchant API のリファレンスをご覧ください。
Content API for Shopping からの改善点
Merchant API を使用すると、Merchant Center のワークフローを自動化して効率化できます。また、Content API for Shopping よりも高度な機能を利用できます。
主なユースケース:
- アカウント管理の自動化
- 自動化されたプロダクト管理
- 広告在庫の自動管理
- カスタム レポートの作成
主な改善点:
- 新機能を含むサブ API:
- 注文の追跡では、ビジネス注文の追跡履歴をサポートし、お客様に正確な配送予定を提供します。また、このシグナルにより、送料無料とスピード配送の拡張リスティングも有効になります。
- 問題の解決では、Merchant Center UI で利用できるのと同じ方法で、診断コンテンツとサポート アクションにアクセスできます。
- Product Studio(アルファ版)は、生成 AI を活用して商品のタイトルと説明を生成、最適化します。アクセスをリクエストするには、このフォームに署名する必要があります。
- Accounts サブ API の新しいリソース。
OmnichannelSettings
無料ローカル リスティング(FLL)やローカル在庫広告(LIA)など、オムニチャネル サービングのアカウント構成を管理します。LfpProviders
は、在庫データについてローカル フィード パートナー(LFP)と連携します。GbpAccounts
は、ローカル店舗データ用の Google ビジネス プロフィール アカウントに接続します。OnlineReturnPolicy
オンライン ポリシーの作成、削除、更新を行うことができます。
- 在庫、商品データ、その他の API の新しいメソッド(以下を含む):
- Products サブ API の新しいメソッド。
ProductsUpdate
を使用すると、ProductInput
に必要なすべてのフィールドを指定しなくても、個々の商品を更新できます。
- メイン データソースだけでなく、次のような複数のデータソースを作成できる機能。
- 商品レビューと販売者レビューのアップロードについて説明します
- Merchant API を使用すると、アカウント データの変更に関する通知を有効にできます。
変更点:
pageSize
の最大値が、API 呼び出しあたり 250 行から 1,000 行に増加しました。DataSources
の作成後に、商品の挿入、プロモーション、商品レビュー、販売者レビューで発生していた遅延が修正されました。
今後の予定:
- Reporting サブ API の
productView
テーブルでclickPotentialRank
の更新された定義をリリースしました。 *clickPotential
に基づく商品のランキングが 1 ~ 1,000 の値に正規化されます。clickPotentialRank
が低い商品でも、検索クエリの条件を満たす販売者の商品の中ではクリックの可能性が最も高くなります。これは、2025 年 7 月 1 日にリリースされる可能性がある非互換性の変更です。
AccountRelationship
リソースのAccountIdAlias
を使用すると、複雑なアカウント構造をより適切に管理できます。たとえば、ショッピングモールでは、販売者の内部 ID(アカウント ID など)の代わりに、ユーザー定義のエイリアスを使用します。
gRPC のサポート
Merchant API は gRPC と REST をサポートしています。Merchant API には gRPC を、Content API for Shopping には REST を同時に使用できます。
Merchant API クライアント ライブラリには gRPC が必要です。
詳細については、gRPC の概要をご覧ください。
互換性
このガイドでは、Merchant API 全体に適用される一般的な変更について説明します。
Merchant API は、既存の Content API for Shopping の機能と連携するように設計されています。
たとえば、既存の Content API for Shopping v2.1 products
実装と並行して Merchant Inventories API を使用できます。Content API for Shopping を使用して(実店舗で販売する)新しいローカル商品をアップロードし、Merchant Inventories API の LocalInventory
リソースを使用してその商品の店舗内情報を管理できます。
Content API からの改善点
Merchant API は、次の点で Content API よりも優れています。
- 独自の統合のための新機能を含むサブ API
- 在庫、商品データ、その他の API の新しいメソッド
- メイン データソースだけでなく、次のような複数のデータソースを作成できる機能。
- 商品レビューと販売者レビューのアップロードについて説明します
- Merchant API を使用すると、アカウント データの変更に関する通知を有効にできます。
- Accounts リソースのフィルタリング機能を導入
これらの変更について詳しく見てみましょう。
バージョニングとサブ API
Merchant API では、バージョニングとサブ API のコンセプトが導入されています。モジュラー設計により、必要なサブ API に集中でき、将来の新しいバージョンへの移行も容易になるため、使いやすさが向上します。バージョニングはリクエスト URL に適用されます。この戦略は Google Ads API のエクスペリエンスと似ています。
より堅牢なリクエスト
Merchant API の URL リクエストでは、Merchant API を呼び出すためにさらに多くのパラメータが必要です。これには、リソース、バージョン、名前(識別子)、メソッド(標準以外のメソッド)が含まれます。詳しくは、アカウントとプロダクトの識別子と例をご覧ください。
ID に関する AIP の原則
Content API for Shopping では ID を使用してリソースを識別しますが(例: merchantId
、productId
)、Merchant API では name
識別子を使用して AIP に準拠しています(API 改善原則を参照)。
{name}
識別子には、リソース識別子とその親(または複数の親)が含まれます。{name}
は accounts/{account}/products/{product}
と等しくなります。
すべての読み取り呼び出しと書き込み呼び出しは、リソース識別子として name
フィールドを返します。
{name}
には、コレクション識別子 accounts/
と products/
も含まれます。
Merchant API は、Merchant Center ID を参照するために {account}
を使用し、商品 ID を参照するために {product}
を使用します。
たとえば、getName()
メソッドを実装してリソースから name
を取得し、販売者とリソースの ID から name
を自分で構築するのではなく、出力を変数として保存します。
呼び出しで name
フィールドを使用する方法の例を次に示します。
POST https://merchantapi.googleapis.com/inventories/v1/{PARENT}/regionalInventories:insert
次の表に、Content API for Shopping の products.get
リクエストの変更内容を示します。
Content API for Shopping | Merchant API |
---|---|
GET https://shoppingcontent.googleapis.com/content/v2.1/{merchantId}/products/{productId}
|
GET https://merchantapi.googleapis.com/products/v1/{name}
|
詳しくは、識別子の変更をご覧ください。
別の例として、Merchant API を使用して Merchant Center ID 4321
から ID en~US~1234
の商品を取得する場合は、次のようになります。
GET
https://merchantapi.googleapis.com/products/v1/accounts/4321/products/online~en~US~1234
ここで、{name}
は accounts/4321/products/en~US~1234
と等しくなります。この新しい名前フィールドは、Merchant API のすべての読み取り / 書き込み呼び出しのリソース識別子として返されます。
Content API for Shopping では、コロン(:)は商品名の区切り文字を表しますが、Merchant API では、チルダ(~)がこの機能を実行します。Merchant API の識別子に channel
部分が含まれていません。
たとえば、Content API for Shopping の商品 ID は次のようになります。
channel:contentLanguage:feedLabel:offerId
。
Merchant API の
contentLanguage~feedLabel~offerId
。
子リソースの親フィールド
Merchant API では、すべての子リソースに parent
フィールドがあります。親リソース全体を渡す代わりに、parent
フィールドを使用して、子を挿入するリソースの {name}
を指定できます。list
で parent
フィールドを使用することもできます。
たとえば、特定の商品アイテムのローカル在庫を一覧表示するには、list
メソッドの parent
フィールドで商品アイテムの name
を指定します。この場合、指定された product
は、返された LocalInventory リソースの parent
です。
GET
https://merchantapi.googleapis.com/inventories/v1/{parent}/localInventories
商品 en~US~1234'
とアカウント 4321
のすべてのローカル在庫を取得する場合、リクエストは次のようになります。
GET
https://merchantapi.googleapis.com/inventories/v1/accounts/4321/products/online~en~US~1234/localInventories</code>
親は accounts/{account}/products/{product}
です。この場合、アカウントは商品リソースの親であるため、localInventories リソースには名前識別子(accounts/
と products/
)に含まれる 2 つの親があります。
共通の列挙型
共通の列挙型を使用すると、一貫性が高まります。
Destination.DestinationEnum
フィールドは、リソースを表示するサーフェスを指定します。DestinationEnum
には、目的地ターゲティングで使用可能なすべての値が一覧表示されます。また、プロモーション属性など、サブ API 全体で統一されています。
ReportingContext.ReportingContextEnum
フィールドは、アカウントと商品の問題が適用されるコンテキストを表します。このフィールドは、レポート方法全体で使用されます(IssueSeverityPerReportingContext
など)。
下位互換性
Merchant API の使用を開始しても、既存の Content API for Shopping の統合は中断されることなく引き続き機能します。詳細については、互換性をご覧ください。
サブ API を Merchant API に移行したら、移行したサブ API には Merchant API のみを使用することをおすすめします。
リモート プロシージャ コール(gRPC)の可用性
gRPC は、Merchant API と統合するための新しい推奨方法です。
メリットは次のとおりです。
- 言語に依存しない
- プロトコル バッファに依存する
HTTP/2 を使用して、高性能でスケーラブルなソリューションを提供する(RPC リファレンス)
Google のクライアント ライブラリまたはコードサンプルを使用する場合、gRPC はデフォルトの転送メカニズムです。
gRPC の詳細については、以下をご覧ください。
カスタム バッチ処理が組み込みバッチ処理になる
バッチ処理は、非同期呼び出しを使用するとより効率的に実行されます。Merchant API でバッチ処理を実現するために並列呼び出しを使用する方法と、同時リクエスト用にコードをリファクタリングする方法についてご確認ください。
移行を迅速に進めるには、クライアント ライブラリを使用することをおすすめします。
Merchant API は、Content API for Shopping で提供されている customBatch
メソッドをサポートしていません。代わりに、複数のリクエストを一度に送信するか、呼び出しを非同期で実行してください。
次の Java サンプルは、商品入力を挿入する方法を示しています。
import com.google.api.core.ApiFuture;
import com.google.api.core.ApiFutureCallback;
import com.google.api.core.ApiFutures;
import com.google.api.gax.core.FixedCredentialsProvider;
import com.google.auth.oauth2.GoogleCredentials;
import com.google.common.util.concurrent.MoreExecutors;
import com.google.shopping.merchant.products.v1.Availability;
import com.google.shopping.merchant.products.v1.Condition;
import com.google.shopping.merchant.products.v1.InsertProductInputRequest;
import com.google.shopping.merchant.products.v1.ProductAttributes;
import com.google.shopping.merchant.products.v1.ProductInput;
import com.google.shopping.merchant.products.v1.ProductInputsServiceClient;
import com.google.shopping.merchant.products.v1.ProductInputsServiceSettings;
import com.google.shopping.merchant.products.v1.Shipping;
import com.google.shopping.type.Price;
import java.util.ArrayList;
import java.util.List;
import java.util.Random;
import java.util.stream.Collectors;
import shopping.merchant.samples.utils.Authenticator;
import shopping.merchant.samples.utils.Config;
/** This class demonstrates how to insert a product input */
public class InsertProductInputAsyncSample {
private static String getParent(String accountId) {
return String.format("accounts/%s", accountId);
}
private static String generateRandomString() {
String characters = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789";
Random random = new Random();
StringBuilder sb = new StringBuilder(8);
for (int i = 0; i < 8; i++) {
sb.append(characters.charAt(random.nextInt(characters.length())));
}
return sb.toString();
}
private static ProductInput createRandomProduct() {
Price price = Price.newBuilder().setAmountMicros(33_450_000).setCurrencyCode("USD").build();
Shipping shipping =
Shipping.newBuilder().setPrice(price).setCountry("GB").setService("1st class post").build();
Shipping shipping2 =
Shipping.newBuilder().setPrice(price).setCountry("FR").setService("1st class post").build();
ProductAttributes attributes =
ProductAttributes.newBuilder()
.setTitle("A Tale of Two Cities")
.setDescription("A classic novel about the French Revolution")
.setLink("https://exampleWebsite.com/tale-of-two-cities.html")
.setImageLink("https://exampleWebsite.com/tale-of-two-cities.jpg")
.setAvailability(Availability.IN_STOCK)
.setCondition(Condition.NEW)
.setGoogleProductCategory("Media > Books")
.addGtins("9780007350896")
.addShipping(shipping)
.addShipping(shipping2)
.build();
return ProductInput.newBuilder()
.setContentLanguage("en")
.setFeedLabel("CH")
.setOfferId(generateRandomString())
.setProductAttributes(attributes)
.build();
}
public static void asyncInsertProductInput(Config config, String dataSource) throws Exception {
// Obtains OAuth token based on the user's configuration.
GoogleCredentials credential = new Authenticator().authenticate();
// Creates service settings using the credentials retrieved above.
ProductInputsServiceSettings productInputsServiceSettings =
ProductInputsServiceSettings.newBuilder()
.setCredentialsProvider(FixedCredentialsProvider.create(credential))
.build();
// Creates parent to identify where to insert the product.
String parent = getParent(config.getAccountId().toString());
// Calls the API and catches and prints any network failures/errors.
try (ProductInputsServiceClient productInputsServiceClient =
ProductInputsServiceClient.create(productInputsServiceSettings)) {
// Creates five insert product input requests with random product IDs.
List<InsertProductInputRequest> requests = new ArrayList<>(5);
for (int i = 0; i < 5; i++) {
InsertProductInputRequest request =
InsertProductInputRequest.newBuilder()
.setParent(parent)
// You can only insert products into datasource types of Input "API", and of Type
// "Primary" or "Supplemental."
// This field takes the `name` field of the datasource.
.setDataSource(dataSource)
// If this product is already owned by another datasource, when re-inserting, the
// new datasource will take ownership of the product.
.setProductInput(createRandomProduct())
.build();
requests.add(request);
}
System.out.println("Sending insert product input requests");
List<ApiFuture<ProductInput>> futures =
requests.stream()
.map(
request ->
productInputsServiceClient.insertProductInputCallable().futureCall(request))
.collect(Collectors.toList());
// Creates callback to handle the responses when all are ready.
ApiFuture<List<ProductInput>> responses = ApiFutures.allAsList(futures);
ApiFutures.addCallback(
responses,
new ApiFutureCallback<List<ProductInput>>() {
@Override
public void onSuccess(List<ProductInput> results) {
System.out.println("Inserted products below");
System.out.println(results);
}
@Override
public void onFailure(Throwable throwable) {
System.out.println(throwable);
}
},
MoreExecutors.directExecutor());
} catch (Exception e) {
System.out.println(e);
}
}
public static void main(String[] args) throws Exception {
Config config = Config.load();
// Identifies the data source that will own the product input.
String dataSource = "accounts/" + config.getAccountId() + "/dataSources/{datasourceId}";
asyncInsertProductInput(config, dataSource);
}
}
Content API で customBatch
を使用しており、Merchant API でこの機能が必要な場合は、フィードバックでお知らせください。
Google Pixel だけの機能
今後の機能は Merchant API にのみ追加されます。(2025 年の年間フィード仕様など、例外もあります)。
Merchant API 固有の機能には、以下が含まれます。
- Reviews API。レビューを使用して、商品とショップの評価を実装、管理します。詳しくは、販売者のレビューと商品のレビューをご覧ください。
- 通知: アカウントの商品データが変更されたときにプッシュ通知を受け取るよう登録します。
価格
Merchant Common パッケージの Price
の変更点は次のとおりです。
Content API for Shopping | Merchant API | |
---|---|---|
金額フィールド | value:string |
amountMicros:int64 |
通貨フィールド | currency:string
|
currencyCode:string |
Price
の金額はマイクロ単位で記録されるようになりました。100 万マイクロが通貨の標準単位に相当します。
Content API for Shopping では、Price
は文字列形式の 10 進数でした。
金額フィールドの名前が value
から amountMicros
に変更されました
通貨フィールド名が currency
から currencyCode
に変更されました。形式は引き続き ISO 4217 です。
最新情報とお知らせ
より詳細な更新については、各サブ API に固有のリリースノートをご覧ください。Merchant API の定期的な更新については、最新の更新をご覧ください。
詳細については、デベロッパー サイトの概要と移行のガイドをご覧ください。
Merchant API とそのサブ API の詳細については、Merchant API の設計をご覧ください。