API 統合を設計して構築する場合に、運用、属性、パラメーターの詳細に注目し過ぎて、統合のパフォーマンス、安定性、保守に大きく影響する可能性のある要因を考慮していないことがよくあります。
そうした注意を払うに値する要因について考えることが、信頼できない統合と盤石な統合との違いを生む可能性があります。できる限り最善の統合を行えるように、ここに挙げる Smartsheet API の 4 つのベスト プラクティスを取り入れることを強くお勧めします。
1. 効率的に: 「一括」処理できる操作を使う
効率を最大限にするため、可能な場合には一括処理が可能な API 操作を使用します。一括処理が可能な API 操作を使うと、1 回の API リクエストで複数のアイテムを追加、更新、削除できます。
例えば、シート内の 10 行を更新する必要がある場合、10 回別々に (各行に 1 回ずつ) リクエストを行うのではなく、複数行の更新リクエストを 1 回使うことでこれを実行できます。
一括処理が可能な操作を使うと、統合が発信しなければならないコール数が劇的に削減するので、効率性が高まります。これにより、レート制限にかかる可能性も減少します (制限に対してはそれぞれの一括操作が 1 回のリクエストにしか数えられないため)。
現在、以下のタスクを一括で完了できる API 操作を紹介します。
今後は「一括」処理可能な操作をさらに追加していく予定です。そうした効率性を高める機会の増強にご期待ください。そして、可能な限り物事を一括で行うことがベスト プラクティスだということを覚えておきましょう。
ヒント: 部分的な成功を認める
通常は、一括処理中にエラーが発生する場合、デフォルトの動作では、操作全体が失敗します。例えば、行の更新リクエストを行ったが、そのリクエスト対象のうちの 1 行が無効であった場合、操作全体が失敗し、1 行も更新されません。
しかし、一括リクエストでの部分的な成功を認めるオプションがあります。部分的な成功を認めると、操作中にエラーが生じる場合であっても、リクエストの正常に処理される部分を実行することができます。
2. 実用的に: レート制限のガイドラインを遵守する
「レート制限超過」エラーの対処
Smartsheet API は現在、アクセス トークンごとに 1 分あたり 300 リクエストというレート制限を課しています。
ファイルの添付やセルの履歴取得など、リソースを集中的に使う特定の操作については、レート制限では 10 リクエストとして数えます。このレート制限を超過すると、続く API リクエスト (1 分以内のもの) には、次の JSON 応答本文とともに 429 HTTP ステータス コードが返されます。
{
“errorCode”: 4003,
“message”: “Rate limit exceeded.”
}
このレート制限エラーにうまく対処できるように統合を設計することをお勧めします。適切に対処できる方法の 1 つは、このエラーが生じた場合に統合を 60 秒間スリープさせてから次のリクエストを再試行するというものです。
もう 1 つ、エクスポネンシャル バックオフを実装する方法もあります。これは失敗したリクエストを定期的に再試行するエラー処理戦略で、リクエストが正常に完了するか試行回数が特定の回数に達するまで試行間隔を次第に長くしていくものです。
「連続的な」更新の実行を避ける
また、API リクエストを立て続けに実行して、ごく短時間に特定の Smartsheet オブジェクトを繰り返し何度も更新することも避けるよう強くお勧めします。
例えば、統合が毎秒同一シートの行の更新リクエストのみを行っているとしたら、これを合計するだけで毎分 60 リクエストに達します。これはレート制限ガイドラインの範囲内です。
しかし、同じオブジェクトをそのように連続的に更新していたのでは、統合にも Smartsheet プラットフォームでのユーザー エクスペリエンスにも悪い影響を与える保存エラーにつながる可能性があります。
こうしたシナリオを避けるため、同じ Smartsheet オブジェクトに対して立て続けに API リクエストを実行することがないように統合を設計します。効率性を最大限にするため、変更をひとまとめにして、「一括」処理が可能な操作 (行の更新や列の追加等) を使った 1 回のリクエストで送信することを検討します。
リクエストの連続実行
また、特定の Smartsheet オブジェクトを更新するために複数の API リクエストを並行して実行することも避けるべきです。平行して行うと、パフォーマンスが下がる結果となりますし、保存が競合するためにエラーが生じる可能性も高いです。
こうしたシナリオを避けるため、特定の Smartsheet オブジェクトを更新する API リクエストのような統合を設計する場合は、必ず連続で行うようにします。つまり、1 度に 1 つのリクエストを実行し、前のリクエストが完了するまで次のリクエストを開始しないということです。
3. スマートに: エラーは適切に処理する
API リクエストが正常に完了すると、実行された操作に従った応答本文のデータとともに、200 HTTP ステータス コードが返されます。しかし、何か問題が生じて、200 以外の応答が戻された場合はどうなるでしょうか。エラーを適切に処理する能力は、質の高い API 統合の重要な要素です。
Smartsheet API リクエストが正常に完了しない場合、API は、発生したエラーに関する詳細を記述する JSON 応答本文とともに、4xx または 5xx という HTTP ステータス コードを返します。例えば、不正な (存在しない) シート ID を使ってシートの取得リクエストを実行する場合の応答では、次のような JSON 応答本文とともに 404 という HTTP ステータス コードが返されます。
{
“errorCode”: 1006,
“message”: “Not Found”
}
いつ再試行するべきでしょうか。
正常なエラー処理戦略では、リクエストを再試行することで解決可能なエラーと自動的に再試行してはいけないエラーとの違いを、統合で認識する必要があります。
応答で返される HTTP ステータス コードは、リクエストの結果に関して最初に得る表示です。
エラー処理の推奨事項
HTTP ステータス コードに加え、正常に処理されなかったリクエストについての応答本文で返される Smartsheet 独自のエラーコードも評価する必要があります。例:
{
“errorCode”: 1006,
“message”: “Not Found”
}
API ドキュメントには、各 Smartsheet 独自のエラー コードについて、エラー処理の推奨事項が記載されています。以下のガイドラインに従い、この情報を使ってエラー処理ロジックを実装することをお勧めします。
-
エラー コードが永続的なエラー状態を示している場合は、リクエストを再試行しません。
-
エラー コードが修正可能な問題を示している場合は、その問題が修正されるまではリクエストを再試行しません。
-
エラー コードが時間をおいて再試行することで解決できる問題を示している場合は、エクスポネンシャル バックオフを使ってリクエストを再試行します。
4. 勤勉に: ロギングを実装する
理想的な世界であれば、統合は初日からシームレスに機能し、どのような問題のトラブルシューティングも必要ありません。
しかし残念ながら、そのようなケースは稀です。問題が生じた場合には、統合で API リクエストと応答をロギングできることが重要です。
API の問題が起こったときに生のリクエストと応答 (詳細なエラー コードとエラー メッセージを含む) にアクセスできれば、トラブルシューティングを能率化し、解決までにかかる時間を短縮できます。
以下の例は、API リクエストと応答についてアプリケーションで記録すべき情報の種類を示しています。
リクエスト: 動詞、URI、ヘッダー、リクエスト本文
POST https://api.smartsheet.com/2.0/sheets/4098273196697476/columns
Authorization: Bearer MY_TOKEN
Content-Type: application/json
Request body:
[
{
"title": "FIRST COLUMN - My New Column",
"index": 0,
"type": "TEXT_NUMBER"
},
{
"title": "FIRST COLUMN - My New Column",
"index": 1,
"type": "TEXT_NUMBER"
}
]
応答: HTTP ステータス コード、応答本文
HTTP status: 400 Bad Request
Response body:
{
"errorCode": 1133,
"message": "Column titles are not unique among input columns.",
"detail": {
"columnTitle": "FIRST COLUMN - My New Column"
}
}
多くの場合、こうした情報にアクセスすることで、自分で問題を特定して解決することができます。解決が難しい場合には、devrel@smartsheet.com に連絡してサポートを求めることができます。トラブルシューティングを行うため、上記のリクエスト/応答に関する情報が必要になります。
初めて統合を設定するときには API リクエストと応答のロギングを実装しておくとよいでしょう。そうすれば、より効率的な体験を実現できるようになるからです。
統合の構築を始める
現在 Smartsheet を使って統合を設計および構築している途中であっても、以前に統合を構築したのであっても、この投稿で触れたベスト プラクティスを取り入れるなら今が最善です。
また、この投稿で説明したリソースやガイダンスについては、ぜひ Smartsheet 開発者ポータルを最大限に活用してください。いずれも、Smartsheet API を使いこなすまでにかかる時間を短縮し、自信を持ってソリューションを導入するのに役立つように用意されているものです。
Smartsheet IT ニュースレターを購読して、IT 専門家がビジネスへの影響力を高めるためのヒント、戦略、アイデアをご確認ください。