Shopify 公式ヘッドレスコマースフレームワーク Hydrogen の登場により、Storefront API の役割が大きくなりました。本記事では Storefront API の基本を調査・解説していきたいと思います。
Storefront API とは
Storefront APIは、 Web サイト、スマホアプリ、ビデオゲームなどでの購入体験を開発するために用います。既存のオンラインショップや POS では満たせない顧客体験を実現する際に利用します。顧客が商品やコレクションを閲覧し、商品をカートに追加し、チェックアウトすることを可能にする機能を提供します。
以下のユースケースで利用出来ます。
- Shopify サイトでは表現しきれないリッチな体験や他サービス・業務との連携
- Shopify 以外の Web サイト（自社メディア）でショップの商品を販売する
- スマホアプリでショップの商品を販売する
- Unity で開発したビデオゲーム上でショップの商品を販売する
Storefront API の概要
Shopify の API 郡は大きく分けると管理者のための Admin API とエンドユーザーのための Storefront API になります。
Admin API は GraphQL と REST API があります。Admin API のアクセストークンの取得方法はこちらの記事で解説しています。
Storefront API は GraphQL で提供されています。REST API はありません。API リクエストするための JavaScript, Node.js, iOS, Android など公式の SDK や React ベースのヘッドレスコマースサイトを構築するためのフレームワーク Hydrogen があります。以下にて解説していますのでご覧ください。
以降 npm ライブラリ（@shopify/shopify-api) と Hydrogen のサンプルを記載します。
データ構造
Storefront API で利用できる代表的なデータ構造は以下です。
- カート（Cart）
- チェックアウト（Checkouts）
- 共通（Common objects）
- お客様（Customers）
- ストア（Online Store）
- 注文（Orders）
- 商品（Products）
以下、主要なデータ構造を記載します。これらはメタフィールドの設定も可能です。
お客様（Customers）
Customer
お客様は、カートを操作している購入者の情報の項目です。
（出典）Checkout v2022-01 を元に加工
注文（Orders）
├ Checkout
チェックアウトは、支払いの項目です。
（出典）Checkout v2022-01 を元に加工
⇔ Customer
お客様は、カートを操作している購入者の情報の項目です。
（出典）Checkout v2022-01 を元に加工
商品（Products）
Product
商品は、商品バリエーションの項目です。コレクションと紐づきます。
（出典）Product v2022-01 を元に加工
├ ProductVariant
商品バリエーションは、１件の注文、１件のチェックアウトの項目です。商品と紐づきます。
（出典）ProductVariant v2022-01 を元に加工
├ Checkout
チェックアウトは、支払いの項目です。
（出典）Checkout v2022-01 を元に加工
⇔ Collection
コレクションは、商品と紐づきます。
（出典）Collections v2022-01 を元に加工
Hydrogen コンポーネント郡
Hydrogen で提供されているコンポーネント郡もデータ構造の参考になるかと思います。こちらの記事でドキュメントを日本語訳しているのでご覧ください。
認証
Storefront API は未認証（unauthenticated）で使えます。つまり、すべてのユーザーが読み取り専用でアクセスでき、ユーザー名やパスワードは必要ありません。Storefront API を有効にするアプリは、OAuth時、またはShopify管理画面での認証時に、関連する未認証のアクセススコープを明示的に要求する必要があります。
const adminApiClient = new Shopify.Clients.Rest(
session.shop,
session.accessToken,
);
const storefrontTokenResponse = await adminApiClient.post({
path: 'storefront_access_tokens',
type: DataType.JSON,
data: {
storefront_access_token: {
title: 'This is my test access token',
},
},
});
const storefrontAccessToken =
storefrontTokenResponse.body['storefront_access_token']['access_token'];
// shopify.config.js
export default {
storeDomain: '{shop}.myshopify.com',
storefrontToken: {your_storefront_access_token},
storefrontApiVersion: '2022-04',
};
エンドポイントとクエリ
Storefront API は GraphQL で提供されているため１つのエンドポイントで、POST のみ受け付けています。バージョンは随時更新されていきます。
POST
https://{store_name}.myshopify.com/api/2022-01/graphql.json
// Load the access token as per instructions above
const storefrontAccessToken: string;
// Load the current session
const session = await Shopify.Utils.loadCurrentSession(req, res);
// StorefrontClient takes in the shop url and the Storefront Access Token for that shop.
const client = new Shopify.Clients.Storefront(
session.shop,
storefrontAccessToken,
);
// Use client.query and pass your query as `data`
const products = await client.query({
data: `{
products (first: 3) {
edges {
node {
id
title
}
}
}
}`,
});
import {useShopQuery} from '@shopify/hydrogen';
const queryString = gql`
query products {
shop {
products(first: 3) {
edges {
node {
id
title
}
}
}
}
}
`;
const {data} = useShopQuery({
query: queryString,
});
レート制限
Storefront APIは、時間でレートが制限されます。リクエスト数ではなく、リクエストが完了するまでにかかる時間が使用されます。詳細はこちらを参照してください
| API | レート制限方式 | Shopify | Shopify Plus |
|---|---|---|---|
| Storefront API (GraphQL) | 時間ベースの制限 | 1リクエストあたり最小0.5秒、1ユーザーIPあたり60秒 | 1リクエストあたり最小0.5秒、1ユーザーIPあたり120秒 |
標準設定は以下
- バケットレートは60秒/アプリ/リクエストIPアドレス
- リークレートは1/second
おわりに
GraphQL で提供されている Storefront API を利用することで Liquid を利用せずに JavaScript, React 等の使い慣れた言語で Shopify サイトを構築することが出来るようになります。Hydrogen でヘッドレスコマースサイトを構築する記事も書いていますので是非ご覧ください。
| 更新日 | 更新内容 |
|---|---|
| 2022-03-20 | 初版作成 |
| 2022-03-21 | 主要データ構造追記 |
（出典）GraphQL Storefront API を元に加筆・翻訳