REST APIv2について

最終更新日: 08 年 2023 月 XNUMX 日

概要

LogicMonitorのRESTAPIのv2を使用すると、ダッシュボード、デバイス、レポート、Webサイト、アラート、コレクター、データソース、SDTなどのLogicMonitorリソースをプログラムでクエリおよび管理できます。 利用可能なリソースとメソッドの包括的なドキュメントは、 Swaggerドキュメント。 追加情報は、以下のセクションにあります。

注: 認証、レート制限、バージョン管理情報など、LogicMonitorのREST APIに関する一般的な情報については、を参照してください。 このページ。 リクエストはデフォルトでAPIのv1になり、「?v = 2」クエリパラメータを含めるか、「X-Version:2」ヘッダーを含めることでv2リクエストを行うことができます。

REST APIv2での変更

LogicMonitorのRESTAPIのv2は、v1との多くの違い(下位互換性のないものを含む)を備えています。 次のセクションでは主な違いを強調していますが、詳細についてはv2の方法とリソースを確認してください。

ステータスコード

APIのv1では、応答に200つのステータスコードがありました。HTTPステータスコード(ほとんどの場合2)と、応答本文の異なるLMステータスコードです。 vXNUMXでは、XNUMXつのHTTPステータスコードを返し、返される可能性のあるステータスコードのリストを大幅に絞り込みました。 この変更は、応答コードが可能な限り意味のある実用的なものになるようにするために行われました。

レスポンスボディ構造

APIのv1では、成功した応答には、応答の最上位にある「status」、「errmsg」、および「data」オブジェクトが含まれていました。 v2では、HTTPステータスがLMステータスと一致するようになったため、応答が成功すると、「データ」の内容が最上位に返されます。 失敗した応答には、エラーメッセージフィールドが含まれます。 これは、APIのv1用に記述され、API応答を解析するように構成されたスクリプトを、これを反映するように調整する必要があることを意味することに注意してください。

応答の前後の例を次に示します。

HTTP 200 
Response Body:
{ 
"status":200, 
"errmsg":"OK", 
"data": { 
     "id":34, 
     "name":"Prod Server 1" 
 } 
}
v1(前)
HTTP 200
Response Body:
{
     "id":34,
     "name":"Prod Server 1"
}
v2(後)

基本認証のサポートなし

APIのv2での基本認証のサポートを削除しました。 多くの追加の利点(UI / APIアクセスの分離、監査ログエントリ、より安全)があるため、認証のためのAPIトークンの使用を促進するためにこれを行いました。

PATCHのサポート

v2には、ほとんどのリソースのHTTPPATCHのサポートが含まれています。 これは、PUTを使用してリソース全体(すべてのフィールド)を更新する代わりに、リソースのXNUMXつのフィールドのみを更新する場合に便利です。 特定のリソースでPATCHがサポートされているかどうかを判断するには、 Swaggerドキュメント.

フィルタ構文

特殊文字を使用してクエリパラメータ値をフィルタリングするには、エンコードが必要です。 具体的には:

  • 特殊文字「+」を含むフィルタークエリパラメーター値は、XNUMX回エンコードする必要があります。

    たとえば、このリクエストのパラメータ値 GET /device/devices?filter=name:"Prod+Server" 次の結果を得るには、XNUMX回エンコードする必要があります。 "Prod%252BServer"

  • 「+」(&、-など)を除く特殊文字を含むフィルタークエリパラメーター値は、一度エンコードする必要があります。

    たとえば、このリクエストのパラメータ値 GET /device/devices?filter=name:"Prod&Server" 次の結果のために、一度エンコードする必要があります。 "Prod%26Server"

ステータスコード

リクエストが失敗した場合、レスポンスの本文には、次のコードのいずれかを含む「errorCode」フィールドが含まれます。

HTTPステータスコード APIv2エラーコード 説明
202 1202 リクエストは処理のために受け入れられましたが、処理は完了していません
400 1400 不正なリクエスト(たとえば、他の何かがリソースに依存しているため、リソースを削除できません)
401 1401  認証に失敗しました
402 支払いが必要; 顧客アカウントがこの機能を許可されていない場合に返されます。
403  1403  認証は成功しました。 アクセス拒否
404  1404  そのようなリソースはありません
409  1409  リソースはすでに存在します
412  1412  前提条件が満たされていません(例:XNUMX要素認証)
413  1413  リクエストエンティティが大きすぎます(たとえば、レポートが大きすぎて生成できません)
422 処理できないエンティティ
429  1429 リクエストが多すぎます(レート制限を超えています) 
500  1500 内部エラー

GET /device/devices?v=2&fields=name,id&size=2
HTTP 200 
Response Body:
{
"total": 222,
"items": [
{
"id": 3,
"name": "ilo-mx233700hu.usa.lab"
},
{
"id": 5,
"name": "idrac-r610.csc.lab"
}
],
"searchId": null,
"isMin": false
}
GET /device/devices?v=2&fields=name,id&size=2 
HTTP 404 
Response Body:
{
"errorMessage": "Authentication failed",
"errorCode": 1401,
"errorDetail": null
}
記事上で