2021年10月版のAPI機能リリースのまとめにようこそ。アプリの品質向上のために最新の変更を適用したり、開発環境を合理化したりするのに役立つ情報をお届けします。
今回のバージョンには、刷新されたCart APIと特定のリソースをIDで取得できる機能など、Storefront APIの大幅な改良が含まれます。また、Bulk Operation Webhooks、予約注文などを簡単に管理できるようにするManual Fulfillment Holds、お客さまがSMSのマーケティングコミュニケーションを受けとるという同意を示すSMS marketing consent endpointsなども含まれています。
今回のリリースにより、2020-10バージョンが削除となりますので、互換性の確保のためAPIヘルスレポートのチェックと、今後の変更の確認を忘れずにお願いします。このバージョンに関連するAPI変更の全体リストは、2021-10リリースノート(英語)でご確認いただけます。
Shopifyマーチャント向けのアプリを構築する
Shopifyアプリストア向けのアプリ開発、カスタムアプリの開発サービス、ユーザーベースの成長促進、あなたが望むことがなんであれ、Shopifyパートナープログラムがその成功をサポートします。無料で登録して、教育リソース、開発者プレビュー環境、継続的な収益シェアプログラムを利用しましょう。
1 Cart API
これまで、Storefront APIでカートを管理する場合にいくつかの大きな障害がありました。リアルタイムで商品の在庫や価格、割引などを取得する唯一の方法は、チェックアウトの作成か更新でした。Shopifyは、お客さまの体験を高いレベルに維持するために慎重にチェックアウトを制限します。この「擬似カート」を管理するリクエストは、チェックアウトスロットルの制限にカウントされます。
2021-10バージョンでは、Storefront APIを使用してカートと直接やり取りすることが可能です。このCart APIは、ユーザビリティの飛躍的な進歩であり、お客さまの支払い準備ができるまではチェックアウトの作成を必要とせずに次の注文に関する文脈的なすべての情報を取得可能にします。さらに、これらのカートはチェックアウトスロットルに関連付けされません。かわりに、ほかのストアフロントのリクエストと同じスロットルが考慮されます。フラッシュセールはこのアップデートから大きなメリットを享受できます。チェックアウトのキューは、Storefront APIで作成されたカートで利用可能になりました。
Storefront APIでカートを作成するミューテーションの例がこちらです。
mutation createCart($cartInput: CartInput) { | |
cartCreate(input: $cartInput) { | |
cart { | |
id | |
lines(first:10) { | |
edges { | |
node { | |
merchandise { | |
... on ProductVariant { | |
product { | |
title | |
} | |
title | |
} | |
} | |
} | |
} | |
} | |
attributes { | |
key | |
value | |
} | |
estimatedCost { | |
totalAmount { | |
amount | |
currencyCode | |
} | |
subtotalAmount { | |
amount | |
currencyCode | |
} | |
totalTaxAmount { | |
amount | |
currencyCode | |
} | |
totalDutyAmount { | |
amount | |
currencyCode | |
} | |
} | |
} | |
} | |
} |
変数です:
{ | |
"cartInput": { | |
"lines": [ | |
{ | |
"quantity": 1, | |
"merchandiseId": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0VmFyaWFudC8zOTMwODkwMDQ2NjcxMA==" | |
} | |
], | |
"attributes": { | |
"key": "cart_attribute", | |
"value": "This is a cart attribute" | |
} | |
} | |
} |
その後にAPIは1つのカートデータを返します
{ | |
"data": { | |
"cartCreate": { | |
"cart": { | |
"id": "Z2lkOi8vc2hvcGlmeS9DYXJ0LzJmYTcyNzk0ZWJkZmQ2YmJjYzdkMjljMGM5OWJlNDMx", | |
"lines": { | |
"edges": [ | |
{ | |
"node": { | |
"merchandise": { | |
"product": { | |
"title": "Good Shirt" | |
}, | |
"title": "Small" | |
} | |
} | |
} | |
] | |
}, | |
"attributes": [ | |
{ | |
"key": "cart_attribute", | |
"value": "This is a cart attribute" | |
} | |
], | |
"estimatedCost": { | |
"totalAmount": { | |
"amount": "58.0", | |
"currencyCode": "CAD" | |
}, | |
"subtotalAmount": { | |
"amount": "58.0", | |
"currencyCode": "CAD" | |
}, | |
"totalTaxAmount": null, | |
"totalDutyAmount": null | |
} | |
} | |
} | |
} | |
} |
Storefront APIでカートを管理する方法(英語)の詳細はドキュメントでご確認いただけます。
2 Storefront APIの改良
個別リソースを取得するのを簡単にするため、QueryRootに新しいフィールドが追加されました。たとえば、ブログ、コレクション、ページ、商品をIDやハンドルで直接クエリ可能です。このフィールドは、必要なリソースを素早く効率的に取得できるようにします。インデックスから返された全リソースのリストを探したり、検索エンドポイントを使ってGraphQLのレスポンスの各リソースごとにedgesとnodesを行ったり来たりする必要はありません。
以下は、個々の商品をハンドルから取得するGraphQLクエリの例です。
{ | |
product(handle:"good-shirt"){ | |
id | |
title | |
priceRange { | |
minVariantPrice { | |
amount | |
currencyCode | |
} | |
} | |
onlineStoreUrl | |
} | |
} |
レスポンスがこちらです:
{ | |
"data": { | |
"product": { | |
"id": "Z2lkOi8vc2hvcGlmeS9Qcm9kdWN0LzU2MTM4ODk0ODY4NzA=", | |
"title": "Good Shirt", | |
"priceRange": { | |
"minVariantPrice": { | |
"amount": "58.0", | |
"currencyCode": "CAD" | |
} | |
}, | |
"onlineStoreUrl": null | |
} | |
} | |
} |
3 Bulk Operation Webhooks
以前のバージョンでは、Shopifyが処理を完了したときを知るには一括操作のステータスをポーリングする必要がありました。2021-10のリリースには、一括処理の完了、失敗、キャンセルについてクライアントに通知するwebhookが含まれています。webhookはAPIコール制限における一括操作の影響をさらに軽減し、一括操作のステータスを含むwebhookのレスポンスを待てばいいだけになっています。もうポーリングの必要はありません!
Bulk Operation Webhooksのサブスクリプションを作成するミューテーションの例が下記になります。花
mutation { | |
webhookSubscriptionCreate( | |
topic: BULK_OPERATIONS_FINISH | |
webhookSubscription: { | |
format: JSON, | |
callbackUrl: "https://12345.ngrok.io/"} | |
) { | |
userErrors { | |
field | |
message | |
} | |
webhookSubscription { | |
id | |
} | |
} | |
} |
一括操作が完了したら特定のURLに送信されるペイロードの例がこちらです。
{ | |
"admin_graphql_api_id": "gid://shopify/BulkOperation/720918", | |
"completed_at": "2019-08-29T17:23:25Z", | |
"created_at": "2019-08-29T17:16:35Z", | |
"error_code": null, | |
"file_size": "358", | |
"object_count": "57", | |
"partial_data_url": null, | |
"root_object_count": "57", | |
"status": "completed", | |
"type": "query", | |
"url": "https://storage.googleapis.com/shopify/dyfkl3g72empyyoenvmtidlm9o4g?<params>" | |
} |
詳しくは、ドキュメントのGraphQL Admin APIによるbulk operationの実行(英語)をご確認ください。
4 Manual Fulfillment Holds
2021-10バージョンには、Fulfillment Ordersを使用するクライアントのフルフィルメントワークフローをよりパワフルにするサポートが追加されています。Fulfillment Ordersは「hold」のアクションをサポート可能となり、バックオーダーや予約注文などのアイテムがフルフィルメントで利用可能となる前にアプリがフルフィルメントを保留に設定できます。
以下は、fulfillment orderをholdにするためのミューテーションの例です。
mutation fulfillmentOrderHold($fulfillmentHold: FulfillmentOrderHoldInput!, $id: ID!) { | |
fulfillmentOrderHold(fulfillmentHold: $fulfillmentHold, id: $id) { | |
userErrors { | |
field | |
message | |
} | |
fulfillmentOrder { | |
status | |
fulfillmentHolds { | |
reason | |
reasonNotes | |
} | |
} | |
} | |
} |
変数です:
{ | |
"fulfillmentHold": { | |
"reason": "OTHER", | |
"notifyMerchant": false, | |
"reasonNotes": "Preorder" | |
}, | |
"id": "gid://shopify/FulfillmentOrder/4849406902294" | |
} |
こちらがレスポンスです:
{ | |
"data": { | |
"fulfillmentOrderHold": { | |
"userErrors": [], | |
"fulfillmentOrder": { | |
"status": "ON_HOLD", | |
"fulfillmentHolds": [ | |
{ | |
"reason": "OTHER", | |
"reasonNotes": "Preorder" | |
} | |
] | |
} | |
} | |
} | |
} |
これらの新しいアクションは、従来のfulfillment platformではなく、Fulfillment Ordersによって利用可能となります。わたしたちはフルフィルメントを操作するクライアントが従来のOrder Fulfillment EndpointではなくFulfillment Ordersを使っておこなうことを強く推奨します。
5 SMS Consent
APIクライアントは、SMSでマーケティング資料を受け取ることのお客さまの同意を取得、追加、更新できるようになりました。この設定を更新すると、CUSTOMERS_MARKETING_CONSENT_UPDATE webhookがトリガーされ、お客さまのマーケティング設定をつねに最新の状態で把握できます。
これらの設定は、customerSmsMarketingConsentUpdateミューテーションによって更新されます。下記がその例になります。
mutation customerSmsMarketingConsentUpdate($input: CustomerSmsMarketingConsentUpdateInput!) { | |
customerSmsMarketingConsentUpdate(input: $input) { | |
userErrors { | |
field | |
message | |
} | |
customer { | |
id | |
firstName | |
smsMarketingConsent { | |
marketingState | |
consentUpdatedAt | |
} | |
} | |
} | |
} | |
変数がこちら:
{ | |
"input": { | |
"customerId": "gid://shopify/Customer/3059605602326", | |
"smsMarketingConsent": { | |
"marketingState": "SUBSCRIBED", | |
"marketingOptInLevel": "CONFIRMED_OPT_IN" | |
} | |
} | |
} |
レスポンスです:
{ | |
"data": { | |
"customerSmsMarketingConsentUpdate": { | |
"userErrors": [], | |
"customer": { | |
"id": "gid:\/\/shopify\/Customer\/3059605602326", | |
"firstName": "Shayne", | |
"smsMarketingConsent": { | |
"marketingState": "SUBSCRIBED", | |
"consentUpdatedAt": "2021-09-29T14:29:55Z" | |
} | |
} | |
} | |
} | |
} |
これはリマインドになりますが、マーケティングアクティビティを実行するすべてのアプリは、お客さまから収集したマーケティング設定に関してShopifyで顧客レコードを更新することが必須になっています。Shopifyにおけるお客さまのマーケティング設定情報が最新状態に保たれることで、ストアのすべてのアプリが個々の顧客マーケティング設定を尊重することができます。
利用可能なmarketing statesとオプトインレベルについての詳細は、customerSmsMarketingConsentUpdateミューテーション(英語)のドキュメントにあります。
変更を随時確認しましょう
Shopifyプラットフォームの変更をチェックするには、新しいプロダクトリリース情報の主要リソースである開発者チェンジログ(英語)を購読してください。チェンジログで最新の情報を得て、次回の2022-01リリース候補の新機能が出たらすぐ採用して一歩先を行きましょう。
パートナーと開発者向けのニュースをお届けするマンスリーShopifyニュースレターを購読することもできます。これもプラットフォームのアップデートを知るうえで役立ちます。
原文:Shayne Parmelee 翻訳:深津望