🧑‍🔧

【Shopify.dev和訳】Apps/Flow/Actions

2021/09/16に公開約12,100字

この記事について

この記事は、Apps/Flow/Actionsの記事を和訳したものです。

記事内で使用する画像は、公式ドキュメント内の画像を引用して使用させていただいております。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Shopify のフローアクション

アクションとは、Shopify Flow のワークフローコンポーネントです。アクションは、特定の条件が満たされたときに店舗やアプリで実行されるタスクを表します。あなたのアプリを Shopify Flow に接続して、ワークフローアクションが実行されたときにあなたのアプリがデータを受け取るようにできます。

このガイドでは、マーチャントがワークフローで使用できるように、アプリにアクションを追加する方法を説明します。

要求事項

  • アプリにトリガーを追加する方法を紹介したトリガーのチュートリアルが終了しました。
  • 以下のものが必要です。
    • インターネットにアクセスできるテスト用のウェブサーバーで、Shopify Flow からの POST リクエストを受け取れるようにします。
    • テストウェブサーバーと連動するテストアプリ
    • Shopify Flow とテストアプリがインストールされている開発ストア

アクションの仕組み

マーチャントがワークフローで使用できるアクションを作成するには、アプリにアクションを追加する必要があります。アクションには、以下の情報を含める必要があります。

  • マーチャントがワークフローにアクションを追加する際に記入する必要のあるフィールド
  • Shopify Flow がアクションのコンテンツ(JSON ペイロード)をあなたのアプリに送る(POST)ために使用する URL
    また、POST リクエストが到着した際にデータを処理し、ステータスコードを Shopify Flow に送り返すようにアプリを設定する必要があります。

また、POST リクエストが到着したときにデータを処理し、ステータスコードを Shopify Flow に送り返すようにアプリを設定する必要があります。

HTTP ステータスコードとリトライの例外

Shopify Flow があなたのウェブサーバーに POST リクエストを送った後、最大 10 秒間HTTP ステータスコードを待ちます。

もし 10 秒経っても Shopify Flow があなたのウェブサーバーからのレスポンスを受け取らなかった場合、Shopify Flow はあなたのウェブサーバーへの接続を閉じ、後ほどリクエストを再送します。

Shopify Flow が応答を受け取ると、次の表に表示されているコードを処理します。

ステータスコード 詳細
200 成功 Shopify Flow は、POST リクエストがあなたのウェブサーバーで処理されたと仮定します。
202 成功 Shopify Flow は、POST リクエストが受理されたものの、あなたのウェブサーバーで処理されなかったと仮定します。Shopify Flow は POST リクエストを最大 24 時間の間、間隔をあけて再送します。
4XX クライアントエラー Web サーバーがRetry-Afterヘッダーなしで 429 ステータスコードを送信した場合、Shopify Flow は最大 24 時間の間、増加する間隔で POST リクエストを再送します。
もしあなたのウェブサーバーが待ち時間を指定したRetry-Afterヘッダー付きの 429 ステータスコードを送信した場合、Shopify Flow は待ち時間(フォーマットは秒単位)が経過した後に POST リクエストを再送します。もしウェブサーバーが他の 4XX コードを送信した場合、Shopify Flow は失敗があったとみなし、POST リクエストを再送しません。
マーチャントは Shopify Flow の中で、あなたのウェブサーバーのレスポンスの生の内容を含む通知を見ます。
例: 400 Bad Request { "error1": "server unresponsive" } 。message という名前のキーを追加することで、マーチャントに優しいエラーの説明を提供することができます。例えば、以下のようになります。
例: { "message": "Finish the onboarding on our website." }
5XX サーバーエラー Shopify Flow は、POST リクエストを最大 24 時間の間、間隔をあけて再送信します。
その他のステータスコード もしあなたのウェブサーバーがこの表に記載されていないコードを返した場合、Shopify Flow は失敗があったとみなし、POST リクエストを再送しません。

アプリが重複したリクエストを処理しないようにする

Shopify Flow からの各リクエストには、リクエストではなく関連するアクションランに固有のaction_run_idが含まれています。この ID はリクエストのボディに含まれています。

action_run_ididempotency keyとして使用して、リクエストがユニークかどうかをチェックすることができます。場合によっては、あなたのアプリが同一のリクエストを複数回受け取る可能性があります。例えば、Shopify Flow は、あなたのレスポンスを時間内に受け取れなかったので、リクエストを再送するかもしれません。あなたのアプリは、重複したリクエストの再処理を避けるために、有効期限が設定されたキャッシュに idempotency キーを保存することができます。

アクションを特定する

アクションを作成すると、そのアクションに action_definition_id が割り当てられます。アクションの action_definition_idは、パートナーダッシュボードの Payload previewで確認することができます。

{
  "shop_id": 0,
  "shopify_domain": "johns-apparel.myshopify.com",
  "action_run_id": "xxxx-xxxx-xxxx-xxxx",
  "action_definition_id": "Log weather changes",
  "properties": {}
}

action_definition_idは、アクションが実行されるときにペイロードの一部として送信されます。Web サーバーがリクエストを受信したときに、action_definition_idが作成したアクションの ID と一致しているかどうかを確認します。

複数のアクションを作成した場合は、action_definition_idを使ってペイロードの内容をソートし、Web サーバーやアプリケーションで処理することもできます。

1. アクションの追加

マーチャントがワークフローで使用できるアクションを作成するには、アプリにアクションを追加する必要があります。以下の手順では、天気情報(都市名と気温)を Web サーバーに保存するアクションを作成します。

  1. パートナーダッシュボードで、Shopify Flow アプリ拡張を開きます。
  • アプリをクリックして、テストアプリを開きます。
  • Extensions をクリックし、Flow をクリックします。
  1. アクションの追加をクリックする。
  2. アクションのタイトルと説明を入力します。例えば、「Log weather」と「Save a log of the weather changes」とそれぞれ入力します。アクションプレビューエリアでは、マーチャントが Shopify Flow でアクションを選択するときに、タイトルとアクションがどのように表示されるかを見ることができます。
  3. Shopify Flow がウェブサーバーに JSON ペイロードを送るために使用する URL を入力する。
  4. フィールドの作成をクリックして、データタイプを選択し、マーチャントがアプリのアクションを選択したときに Shopify Flow に表示されるフィールドを作成してください。例えば、以下の値を含む 2 つのフィールドを作成します。
フィールド
フィールド 1
Date type: ショートテキスト
Field name:ロケーション
Label: 天候変化の場所
Help Text(オプション: {{trigger.location}}を入力すると、自動的に都市名が入力されます。
フィールド 2
Date type: 数字
Field name:気温
Label: 温度(華氏)(小数点以下四捨五入)
Help Text(オプション: {{trigger.location}}を入力すると、自動的に気温が入力されます。

ペイロードのプレビューエリアでは、Shopify Flow があなたのウェブサーバーに送る JSON ペイロードで使用するデータモデルを見ることができます。

  1. Saveをクリックする

Web サーバーの設定

Partner Dashboard でアクションを作成した後、アクションが実行されたときに Shopify Flow が送信する JSON ペイロードをリッスンするために、Web サーバーにサービスを追加する必要があります。

HMAC ヘッダ

セキュリティ上の理由から、ウェブサービスでは、アプリの設定時に作成した API シークレットキーを使用したハッシュベースのメッセージ認証(HMAC)ヘッダーの検証を実施する必要があります。

HMAC ヘッダーの名前は x-shopify-hmac-sha256 です。Ruby ベースの Web フレームワークを使用している場合、ヘッダーの名前は http-x-shopify-hmac-sha256 となります。

検証の仕組み

アクションがワークフロー内で実行されると、Shopify Flow はアクションのコンテンツ(JSON ペイロードと HMAC ヘッダー)を Partner Dashboard でアクションを作成した際に入力した URL にポストします。Web サーバーが POST リクエストを受信すると、HMAC ヘッダー (x-shopify-hmac-sha256、または Ruby ベースの Web フレームワークの場合は http-x-shopify-hmac-sha256) を JSON ペイロードと API シークレットに対して検証する必要があります。

また、Web サーバーは、ペイロードで送信された action_definition_id が、作成したアクションの ID と一致することを確認する必要があります。

HMAC ヘッダーを検証した後は、ペイロードの内容を処理することができます。例えば、ペイロードの内容を Web サーバーのコンソールにログ出力することができます。

3. アクションのテスト

パートナーダッシュボードでアクションを作成し、ウェブサーバーにサポートを追加した後、開発ストアの Shopify Flow でアクションをテストすることができます。

  1. あなたの開発ストアで、アクションを使用するワークフローを作成してください。例えば、「トリガー」ガイドで作成した「天気の変化」トリガーとこのアクションをワークフローに追加します。

  2. ワークフローを起動します。例えば、ウェブサーバーで、Shopify Flow にトリガー情報を送信するイベントを実行します。

ワークフローが完了すると、あなたのウェブサーバーはトリガーのために Shopify Flow に天気情報を送ったことになる。Shopify Flow は、アクションのために情報をコンソールにログするウェブサーバーに、この天気情報を送ったことになる。

次のステップ

  • Shopify Flowに慣れ親しみ、コネクターの構築について学びましょう。
  • あなたのアプリを Shopify Flow に接続して、あなたのアプリで発生するイベントがワークフローのトリガーになるようにします。
  • 有効化されたワークフローであなたのトリガーを使用している店舗について、Shopify Flow からウェブフックを受け取る方法を学びます。

Shopify アプリのご紹介

Shopify アプリである、「商品ページ発売予告アプリ | リテリア Coming Soon」は、商品ページを買えない状態のまま、発売日時の予告をすることができるアプリです。Shopify で Coming Soon 機能を実現することができます。

https://apps.shopify.com/shopify-application-314?locale=ja&from=daniel

Shopify アプリである、「らくらく日本語フォント設定|リテリア Font Picker」は、ノーコードで日本語フォントを使用できるアプリです。日本語フォントを導入することでブランドを演出することができます。

https://apps.shopify.com/font-picker-1?locale=ja&from=daniel

Discussion

ログインするとコメントできます