API エンドポイントのキャッシング

この機能を使用できるユーザー

この機能を使用するには、以下が必要になります。

• API プラットフォーム機能へのアクセス権
• API プラットフォームの権限

Workato の根幹をなすのは、業務の効率化を支援することです。API キャッシング機能は、レシピから発行される同一のリクエストを削減することで、追加的な最適化レイヤーとして機能します。これには、次のような直接的なメリットがあります。

• レシピアクションの応答時間の短縮
• ジョブ総数の削減
• ジョブ実行時間の短縮
• アプリケーション間のトラフィックの削減

このガイドでは、次のようなトピックを取り扱います。

• API キャッシングの仕組み
• キャッシュデータの保持期間
• エンドポイントパラメータを使用したキャッシング
• キャッシングのベストプラクティス
• キャッシングの制限と割り当て
• エンドポイントのキャッシングを有効にする方法
• キャッシュされたエントリを消去する方法
• キャッシュされたエントリを再検証する方法

---

動作の仕組み

API キャッシングを有効にすると、レスポンスは一時的にキャッシュに格納されます。同一のエンドポイントに送信される後続のリクエストでは、(指定時間内の送信であれば) レシピのエンドポイントを利用することなく、キャッシュに格納されたデータが取得されます。これにより、応答時間が短縮され、リソース使用量が低減します。

• キャッシングの基本
• キャッシュの保持
• パスパラメータおよびクエリー文字列パラメータを使用したキャッシング

キャッシングの基本

API キャッシングの概要は以下の通りです。

• キャッシングはエンドポイントごとに設定されます。
• GET メソッドのみがキャッシングをサポートします。
• GET リクエストに対するレスポンスそれぞれが キャッシュエントリ となります。キャッシュエントリにはサイズ制限とワークスペースごとの制限があります。
• キャッシュエントリは、定義した期間保持されます。
• キャッシングでは、パスパラメータやクエリー文字列パラメータの使用がサポートされています。

キャッシュの保持

エンドポイントのキャッシングを設定する際、エントリがキャッシュに保持される時間を定義できます。保持期間 ( Time-to-live ) 内に送信された後続のリクエストは、エンドポイントを再度読み取るのではなく、エントリをキャッシュから取得します。

保持期間が終了すると、エントリはキャッシュから自動的に消去されます。

たとえば、保持期間を 600 秒 (10分) に設定すると、エントリはキャッシュに10分間残り、その後自動的に消去されます。

注 : 各ワークスペースには、キャッシュエントリに 10,000 件という上限があります。この上限に達すると、新しいエントリを格納するために、最も古いエントリが消去されます。

パスパラメータおよびクエリー文字列パラメータを使用したキャッシング

キャッシュされたエントリの保持期間を定義するだけでなく、キャッシュキーとして使用するパスパラメータやクエリー文字列パラメータを定義することもできます。そのキャッシュキーが保持期間内にリクエストと一致した場合、そのリクエストでは対応するエントリがキャッシュから返されます。

パスパラメータとクエリー文字列パラメータはすべて、キャッシュキーに含めることができます。

パスパラメータを使用した例

エンドポイントは /users/{id}、ID は 12345 などの値であるとします。次に挙げるようなリクエストが送信されると、id: 12345 のユーザーに対応するキャッシュ済みエントリがキャッシュから返されます。

curl  -X GET https://api.myworkatoexample.com/docs/users/12345 \
      -H 'API-TOKEN: YOUR_TOKEN'

クエリー文字列を使用した例

エンドポイントは /users?id={value}、ID は 12345 などの値であるとします。次に挙げるようなリクエストが送信されると、id: 12345 のユーザーに対応するキャッシュ済みエントリがキャッシュから返されます。

curl  -X GET https://api.myworkatoexample.com/docs/users?id=12345 \
      -H 'API-TOKEN: YOUR_TOKEN'

---

ベストプラクティス

キャッシングの使用は、頻繁に変更されることがない種類のレコードに対して行うことをお勧めします。そうすれば、古いバージョンのレコードがキャッシュから取得される可能性が低くなります。

キャッシュエントリは、必要に応じて、保持期間が終了する前に手動で消去することができます。

---

制限と割り当て

概要	説明
サポートされているリクエストの種類	ステータスコードが成功 (2xx) になる GET リクエストのみ
キャッシュキーの最大サイズ	10 KB
キャッシュエントリの最大サイズ	10 KB この制限を超えるリクエストは、成功時でもキャッシュされません。注 : この制限を調整するには、Workato のカスタマーサクセスマネージャーまでお問い合わせください。
キャッシュエントリの最大数	ワークスペースあたり10,000件 この値を超えると、新しいエントリを格納するため、最も古いものから新しいものへと順番にエントリが消去されていきます。注 : この制限を調整するには、Workato のカスタマーサクセスマネージャーまでお問い合わせください。

---

エンドポイントのキャッシングの有効化

キャッシングは、新規の GET エンドポイントに対しても、既存の GET エンドポイントに対しても有効化できます。ゼロから始める場合は、まずエンドポイントの作成の手順をたどり、それから以下に進んでください。

1

[Cache response] を ON に切り換えます。

2

[Time-to-live period] フィールドで、保持期間を秒単位で定義します。この期間は、レスポンスがキャッシュ内で、更新や削除の前にどれだけ長い間保存されるかを表します。デフォルトは 600 秒 (10分)、最大値は 3600 秒 (60分) です。

3

[Cache key parameters] フィールドでは、リクエストのマッチングで使用するキーを選択します。

4

設定が完了したら、 [Add endpoint] をクリックします。

キャッシングが有効なエンドポイントでは、以下のように [Cache enabled] バッジが表示されます。

---

エンドポイントのキャッシングの監視

キャッシュされたレスポンスの詳細を表示するには、 [API platform] > [Logs] に移動します。キャッシュ済みのレスポンスを利用したリクエストには、 応答時間 の値の横に [Cached] バッジが表示されます。

---

キャッシュされたエンドポイントデータの消去

キャッシュされたエントリは、定義済みの保持期間に基づいて自動的に消去されます。そのほかにも、エンドポイントのキャッシュ全体を手動で消去することもできます。

1

[API platform] > [API collections] に移動します。

2

消去したいエンドポイントが含まれるコレクションをクリックします。

3

そのコレクションのページで、エンドポイントを見つけます。

4

エンドポイントの右側にある[...] (詳細) メニューをクリックします。

5

[Clear cached responses] をクリックします。

6

確認を求められたら、 [Clear cache] をクリックします。

キャッシュされたエントリの再検証

クライアントは時折、キャッシュ済みのエントリを再検証するようプラットフォームに指示することで、最新状態をリクエストしようとする場合があります。これを実行するには、Cache-Control: max-age=0 ヘッダーを含むリクエストを送信します。

curl https://api.myworkatoexample.com/docs/users/12345 \
-H 'Authorization: Bearer ACCESS_TOKEN' \
-H 'Cache-Control: max-age=0'