ドキュメントID: KB-EV4-API-01 | 製品/サービス: EloView 4 REST API | 対象: インテグレーター、開発者、エンタープライズ顧客
EloView 4 APIのレート制限と高ボリュームインテグレーションのベストプラクティス
EloView REST APIは、エンタープライズ顧客やインテグレーションパートナーがプログラム経由でデバイス情報を取得し、フリートの健康状態を監視し、コンテンツを管理し、アプリケーションを展開できるようにします。この文書では、EloView 4 APIのレート制限、認証の動作、信頼性の高い高ボリュームAPIインテグレーションのためのアーキテクチャのベストプラクティスについて説明します。
💡 概要
EloView 4は、個々の顧客特有のAPI制限を適用しません。最適な信頼性のために、インテグレーションはOAuthトークンをキャッシュし、バルク/複数デバイスのクエリを優先し、同時スレッドを制限し、エラー処理のためにジッターを伴う指数バックオフを実装すべきです。
1. EloView 4 APIのレート制限
EloView 4は、個々のOAuthクレデンシャル、顧客アカウント、ソースIPアドレス、またはAPIエンドポイントごとのレート制限を施行しません。プロダクションAPIの基本URLは次のとおりです:
https://secure-api.eloview.com
| パラメータ | 制限 / 容量 |
|---|---|
| クレデンシャル、アカウント、ソースIP、またはエンドポイントごと | 特定のレート制限は適用されていません。 |
| AWSプラットフォームリクエストレート(共有) | 10,000リクエスト/秒(全顧客で共有)。 |
| AWSプラットフォームバースト容量(共有) | 5,000リクエスト(全顧客で共有)。 |
⚠️ 重要なインテグレーション警告
上記の共有プラットフォーム制限は顧客ごとの予約枠ではありません。パフォーマンスの問題を回避し、プラットフォームの安定性を守るために、インテグレーションは効率的かつ責任あるリソース使用を考慮して設計する必要があります。
2. OAuth認証とトークン管理
不適切なトークンの取り扱いは、回避可能なAPIオーバーヘッドの一般的な原因です。あなたの認証ロジックを以下のルールに基づいて構成してください:
-
トークンの寿命:アクセストークンは24時間有効です(
expires_in = 86400)。 - キャッシュと再利用:アクセストークンはその有効期間全体でキャッシュし再利用してください。すべてのAPIリクエストに新しいトークンを生成しないでください。
-
積極的な更新:期限切れ直前にキャッシュトークンを更新するか、
HTTP 401 Unauthorizedの応答を受け取った直後に更新してください。 - クレデンシャル対容量:アカウント管理者は複数のOAuthクレデンシャルを作成できますが、複数のクレデンシャルを使用しても全体のAPI容量は増加しません。
3. フリートとデバイスの状態の監視
デバイスの健康状態とアクティブな展開を大規模に監視する際は、ネットワークオーバーヘッドを減らすためにクエリ設計を最適化してください:
-
定期的な状態監査:バルククエリエンドポイント(
GET /devicesやPUT /devices/searchなど)を使用して、複数のデバイスの状態記録を単一の呼び出しで取得してください。各キオスクに対してGET /devices/{serial}を個別にポーリングしないでください。 - ポーリング間隔(アイドル):定期的な健康状態および状態チェックの場合、ポーリング間隔は数分ごとで十分です。
-
アクティブな展開の監視:アクティブなインストールを追跡するために、
GET /device/{serial}/content/statusを1〜2分の間隔でクエリしてください。展開が確定状態(成功または失敗)に達したら、ポーリングを停止してください。
4. 複数デバイスへのアプリケーションの展開
POST /deploymentsエンドポイントは、同時に多くのデバイスをターゲティングすることをサポートします。
- ターゲティングフォーマット:シリアル番号、デバイスグループ、またはクエリ条件のリストを使用して、単一のリクエストペイロードで受取人を指定します。
- 空のクエリターゲット:ターゲットクエリを空白にすると、自動的にアカウント内のすべてのデバイスをターゲットします。このパラメータは極めて注意して使用してください。
- バッチ制限:エンドポイントは厳格なシリアル番号制限を施行していませんが、ペイロードはアカウントのバッチサイズ設定とOAuthクレデンシャルのバッチ操作権限に従います。
-
制限超過の応答:アカウントの制限を超えると、
400 BATCH_LIMIT_EXCEEDEDエラーが発生するか、PENDING_FOR_APPROVALが設定されている場合は手動で確認が必要となることがあります。
5. 同時実行性、APIエラー、および再試行
インテグレーションは保守的な同時実行性プロファイルを維持するべきです。アクティブな並列リクエストは5〜10の同時接続に制限してください。キューとバッチ処理を使用して、数千の並列エンドポイントを実行するのではなく、データのストリーミングを行うべきです。
一般的なAPIレスポンスとアクション
| API HTTPステータス | 意味と推奨アクション |
|---|---|
| HTTP 401 Unauthorized | 認証失敗(例:トークンが期限切れまたは無効)。認証クレデンシャルを確認し、新しいトークンを要求してください。 |
| HTTP 429 Too Many Requests | プラットフォームのレート制限。指数バックオフとランダマイズされたジッターを使用して再試行ロジックを実装してください。 |
| 400 BATCH_LIMIT_EXCEEDED | ペイロードサイズが許可されたバッチ実行制限を超えています。アカウント設定を確認し、トランザクションを分割してください。 |
⚙️ 再試行ロジックのバックオフ戦略
HTTP 429レスポンスを処理する際は、再試行スケジュールを進行的に構成してください(例:1秒、2秒、4秒、8秒、16秒、32秒、最大60秒)およびローカライズされたサービスの洪水を防ぐためにランダムな遅延(ジッター)を適用してください。注:プラットフォームが「Retry-After」ヘッダーを返すことは未確認です。
6. 予期しないAPIエラーのトラブルシューティング
インテグレーションに持続的な中断が発生した場合、次の簡単なトラブルシューティングチェックリストを実行してください:
-
基本URLを検証:EloView 4ゲートウェイ(
https://secure-api.eloview.com)を呼び出していることを確認し、レガシーEloView 3ホストではないことを確認してください。 -
ステータスコードを確認: 認証の問題(
HTTP 401)とインフラの制限(HTTP 429)を区別してください。 - 運用メトリクスをレビュー:トークンの再利用の寿命、個々のキオスクのポーリング頻度、バルクエンドポイントの利用、アクティブスレッドの同時実行数をレビューしてください。
📞 テクニカルサポートへのエスカレーション
予期しないAPIの問題が続く場合は、Eloテクニカルサポートにお問い合わせください。調査を迅速化するために、次の情報を提供してください:
- API基本URLと呼び出された特定のエンドポイント
- 公開された送信ソースIPアドレス
- 正確なイベントのタイムスタンプ(タイムゾーンを含む)
- 返されたHTTPステータスコードと完全なレスポンスペイロード
Please report any broken links by emailing elo.support@zebra.com and include a link to the knowledge article