Shopify API リリース：2022年1月版

開発者必見。2022年1月版のAPI機能をまとめました。 今回のバージョンに含まれるのは、Storefront APIによる改良された商品フィルタリング機能、刷新されたProduct Taxonomy API、コレクション・顧客・注文に関する新たなメタフィールドの定義、Order Invoice API、BulkMutationsに関する新しいエラーコード、翻訳可能なリソース・フィーチャー画像・バーコードを取得する簡易的な方法などです。

こちらは2022-01バージョンのShopify APIリリースに関する記事になります。最新機能を活用したアプリの品質向上と開発エクスペリエンスの合理化に役立つ情報をお届けします。

今回のバージョンに含まれるのは、Storefront APIによる改良された商品フィルタリング機能、刷新されたProduct Taxonomy API、コレクション・顧客・注文に関する新たなメタフィールドの定義、Order Invoice API、BulkMutationsに関する新しいエラーコード、翻訳可能なリソース・フィーチャー画像・バーコードを取得する簡易的な方法などです。

また、今回のリリースにより2021-01バージョンが削除となりますので、APIヘルスレポートをチェックして、今後の変更のレビューと互換性の確認をお願いします。このバージョンに関連するすべてのAPI変更のリストは、2022-01リリースノート(英語)に記載されています。

1 Storefront APIを使用したコレクション内の商品フィルタリング

2022-01バージョンから、コレクション内の商品のフィルタリングが可能となり、お客さまに表示する検索結果を絞り込めるようになりました。コレクションに属する商品を取得後、ベンダーや商品タイプ、バリエーションのオプション、在庫の有無といった基準で商品にフィルターをかけられます。

これらのフィルターは組み合わせることも可能なので、より複雑な特性に基づいてコレクションの商品を取得できます。

たとえば、以下のクエリは、下記の属性をすべてもつ商品の取得方法を示しています。

• Type: Shirts & Tops 
• Vendor: Bestshop
• Color: Very Peri

	query MultipleVariantOptions($product_filters: [ProductFilter!]) {
	collectionByHandle(handle: "filterable-collection") {
	handle
	products(first: 10, filters: $product_filters) {
	edges {
	node {
	handle
	availableForSale
	productType
	vendor
	variants(first: 10) {
	edges {
	node {
	selectedOptions {
	name
	value
	}
	}
	}
	}
	}
	}
	}
	}
	}

view raw multiple_variant_options.graphql hosted with ❤ by GitHub

変数がこちら。

	{
	"product_filters": [
	{
	"productType": "Shirts & Tops"
	},
	{
	"productVendor": "Bestshop"
	},
	{
	"variantOption": {
	"name": "color",
	"value": "Very Peri"
	}
	}
	]
	}

view raw multiple_variant_options_variables.json hosted with ❤ by GitHub

コレクション内の商品にフィルターをかけることは、お客さまに関連性が一番高い商品を表示する素晴らしい方法です。Storefront APIを使用してコレクション商品をフィルタリングするための詳しい情報は、こちらのドキュメント(英語)でご確認いただけます。

2 Product Taxonomy API

マーチャントのストアフロントにある商品をお客さまが見つけやすいように整理するなら、新しいProduct Taxonomy APIを使うのがお勧めです。StandardizedProductTypeは定義済みの商品カテゴリー(英語)であり、ストアフロントの商品の探しやすさを向上させます。また、標準のセットタイプに適合することが求められるFacebookなどのチャネルにマーチャントが商品掲載するのを簡単にしています。

事前定義されたカテゴリーにフィットしない商品タイプがある場合、商品オブジェクトのcustomProductTypeフィールド (英語)を使用することができます。これは従来のtypeフィールド同様、文字列です。このカスタムプロダクトタイプは、親カテゴリーが商品に合致するのであれば、親のStandardizedProductTypeと一緒に使用することも可能です。

以下のクエリは、任意のStandardizedProductTypeを取得する例です。

	{
	product(id: "gid://shopify/Product/6911064408086") {
	title
	standardizedProductType {
	productTaxonomyNode {
	name
	fullName
	isLeaf
	isRoot
	}
	}
	}
	}

view raw get_standard_product_type.graphql hosted with ❤ by GitHub

レスポンスです。

	{
	"data": {
	"product": {
	"title": "Stylish Top",
	"standardizedProductType": {
	"productTaxonomyNode": {
	"name": "Shirts & Tops",
	"fullName": "Apparel & Accessories > Clothing > Shirts & Tops",
	"isLeaf": true,
	"isRoot": false
	}
	}
	}
	}
	}

view raw get_standard_product_type_response.json hosted with ❤ by GitHub

商品分類(Product Taxonomy)に関する詳しい情報は、開発者ドキュメントをご覧ください。

3 コレクション・顧客・注文におけるメタフィールドの定義

2021年7月版で、商品のカスタムメタフィールドタイプを可能にするメタフィールドのアップデートがリリースされました。今回のバージョンではこの機能のサポートを、コレクション(Collections)、顧客(Customers)、注文(Orders)に拡大しました。これらの新しいリソースにおけるメタフィールドは、18種類のデータタイプ(英語)を検証する働きも担うため、アプリやストアフロントで表示する有効なデータを保存できます。

以下の例は、商品のレファレンスを保存する顧客メタフィールドの定義を作成するリクエストを示しています。

	mutation metafieldDefitionCreate($definition: MetafieldDefinitionInput!){
	metafieldDefinitionCreate(definition: $definition) {
	createdDefinition {
	id
	key
	description
	ownerType
	}
	userErrors {
	field
	message
	}
	}
	}

view raw metafield_definition_create.graphql hosted with ❤ by GitHub

変数です。

	{
	"definition": {
	"name": "Favourite Product",
	"type": "product_reference",
	"namespace": "my_fields",
	"key": "favourite_product",
	"ownerType": "CUSTOMER",
	"description": "This is the customer's favourite product"
	}
	}

view raw metafield_definition_create_variables.json hosted with ❤ by GitHub

メタフィールドの定義の詳細と、改良された type システムへの移行に関する詳細は、開発者ドキュメント(英語)をご参照ください。

4 Order Invoice API

ShopifyのAPIによって注文に対するインボイスを送信する新しいミューテーションがアプリに追加されました。orderInvoiceSend(英語)ミューテーションによって、注文IDとメール内容を提供し、決済が必要な注文の支払いをお願いするメールをお客さまに直接送ることができます。これは今までマーチャントがマニュアルでおこなっていた作業ですが、自動化することが可能になりました。

お客さまにインボイスを送るミューテーションの例がこちらです。

	mutation orderInvoiceSend($id: ID!, $email: EmailInput) {
	orderInvoiceSend(id: $id, email: $email) {
	order {
	name
	}
	userErrors {
	field
	message
	}
	}
	}

view raw order_invoice_send.graphql hosted with ❤ by GitHub

変数の例です。

	{
	"email": {
	"customMessage": "It's time to pay for your order!",
	"subject": "Order Invoice from Shayne",
	"to": "shayne.parmelee@shopify.com"
	},
	"id": "gid://shopify/Order/4581938462742"
	}

view raw order_invoice_send_variables.json hosted with ❤ by GitHub

このリクエストによってお客さまに送られるメールが以下になります。

このメールはチェックアウトに直にリンクされているため、お客さまは注文の支払いを簡単に完了できます。

orderInvoiceSendミューテーションによるインボイス送信の詳細は、ドキュメント (英語)でご確認いただけます。

5 Bulk Mutation APIのエラーコード

今まで、BulkMutationsが表示するエラーコードは "BULKMUTATIONUSERERRORCODE" のみでした。今回のバージョンから、この汎用エラーコードの代わりに、何が間違っているかがすぐにわかる詳細な新しい5つのエラーコードが提供されます。

この新しいエラーコードの完全リストは、開発者ドキュメント(英語)にあります。

リマインドになりますが、10秒以上の連続したAPIリクエストが必要な場面ではBulkMutation APIがデータをShopifyに同期させるうえで最速かつ一番効率的な方法となります。BulkMutation APIを使ってShopifyにデータを同期する方法の詳細は、ドキュメント(英語)をご覧ください。

6 複数の翻訳可能リソースをIDで取得する方法

一連の特定IDに紐づく翻訳可能なリソースを取得する場合、今までは一度に1つのリソースを得るリクエストを複数回おこなう必要がありました。2022-01バージョンからは、IDの配列を使うことで、指定した一連の翻訳可能リソースを取得することが可能となりました。特定タイプのリソースをすべて取得したり、IDごとに個別のリクエストをしたりせずに済みます。

以下の例は、特定商品の翻訳可能リソースを取得するリクエストと、単一リクエストの2つのバリエーションを示しています。

	{
	translatableResourcesByIds(first: 3, resourceIds: ["gid://shopify/Product/6911064408086", "gid://shopify/ProductVariant/40632128405526", "gid://shopify/ProductVariant/40632128438294"]) {
	edges {
	node {
	resourceId
	translatableContent {
	key
	value
	locale
	}
	}
	}
	}
	}

view raw get_translatable_resources_by_id.graphql hosted with ❤ by GitHub

translatableResourcesByIdsクエリについては、こちらのドキュメント(英語)で詳しい情報を確認できます。

7 新たなStorefront APIの商品フィールド

2022-01バージョンから、Storefront APIは商品のフィールドを新しく2つサポートします。featuredImage フィールドは任意の商品のフィーチャー画像を素早く効率的に取得し、ProductVariant barcode はバリエーションのバーコードを取得できます。

この新しいフィールドを両方得るためのクエリ例がこちらです。

	{
	product(id: "gid://shopify/Product/6911064408086") {
	title
	variants(first: 1) {
	edges {
	node {
	title
	barcode
	}
	}
	}
	featuredImage {
	altText
	height
	width
	}
	}
	}

view raw get_barcode_featured_image.graphql hosted with ❤ by GitHub

レスポンスです:

	{
	"data": {
	"product": {
	"title": "Stylish Top",
	"variants": {
	"edges": [
	{
	"node": {
	"title": "Very Peri",
	"barcode": "01100001011"
	}
	}
	]
	},
	"featuredImage": {
	"altText": "Person wearing a purple shirt",
	"height": 2727,
	"width": 4460
	}
	}
	}
	}

view raw get_barcode_featured_image_response.json hosted with ❤ by GitHub

最新の変更を確認しましょう

Shopifyプラットフォームの変更全部を確認するには、プロダクトアップデートのメインソースである開発者チェンジログ(英語)の購読がおすすめです。開発者チェンジログで最新の情報を得て、2020-04バージョンのリリース候補に新機能が搭載されたらすぐに採用し、一歩先を行きましょう。

パートナーと開発者向けのマンスリーShopifyニュースレターを購読することで、プラットフォームの最新の変更情報を得ることもできます。

原文：Shayne Parmelee　翻訳：深津望