Collector API メソッドと例
Collector 管理 API により、HTTP エンドポイントから Collector や Source を管理できます。このトピックでは、Collector API のパラメータとメソッドについて説明し、エラー コードのリストを示します。
詳細については以下のトピックを参照してください。
- 「API 認証」では、API 認証のオプションについて説明します。
- 「Sumo Logic エンドポイント」では、API クライアントを Sumo Logic API に接続するために使用する API エンドポイントのリストを提供します。
- 「Collector または Source JSON 設定の表示またはダウンロード」では、Web アプリケーションで Collector または Source の JSON 設定を表示またはダウンロードする方法について説明します。
- 「Source API メソッドと例」では、
sourceType
パラメータを指定することであらゆるタイプの Installed Collector と Hosted Collector の Source を作成できる、Source API メソッドについて説明します。 - 「JSON を使用した Source の設定」では、Source パラメータについて説明します。
応答フィールド
以下の表に、Installed Collector と Hosted Collector の API 応答フィールドを示します。
パラメータ | タイプ | 必須 | デフォルト | 説明 | アクセス |
alive | ブール | はい | Collector の実行中に Sumo に対してハートビート メッセージが 15 秒ごとに送信されます。ハートビート メッセージが 30 分間受信できないと、このパラメータは false になります。 |
一時 | |
カテゴリ | 文字列 | 不可 | Null | データの検索時にメタデータとして使用される Collector のカテゴリ。 | 変更可 |
collectorType | 文字列 | Collector タイプ: Installable または Hosted |
変更不可 | ||
collectorVersion | 文字列 | はい | インストールされている Collector ソフトウェアのバージョン。 | 一時 | |
cutoffRelativeTime | 文字列 | 不可 | cutoffTimestamp の代わりに指定することで、現在時刻に対する相対オフセットを指定できます。例: "-1h" 、"-1d" 、"-1w" で、それぞれ 1 時間、1 日、1 週間前の時刻を指定します。 |
変更不可 | |
cutoffTimestamp | Long | 不可 | 0 (すべてのデータを収集) | エポック時刻からのミリ秒で指定したこのタイムスタンプ以降のファイルのみからデータを収集します。 | 変更可 |
description | 文字列 | 不可 | Null | Collector の説明。 | 変更可 |
ephemeral | ブール | はい | true に設定すると、操作が何も行われない状態が 12 時間続いた時点で Collector が削除されます。詳細については、「エフェメラルとしての Collector の設定」を参照してください。 | 変更可 | |
フィールド | JSON オブジェクト | 不可 | Collector に適用するキーと値のフィールド (メタデータ) の JSON マップ。 Collector に Ingest Budget を割り当てるには、フィールド _budget を使用して、割り当てる Ingest Budget の値を指定します。たとえば、予算のフィールド値が Dev_20GB である場合は、次を追加します。fields=_budget=Dev_20GB |
変更可 | |
hostName | 文字列 | 不可 | Null | Collector のホスト名。ホスト名は最大 128 文字です。 | 変更可 |
id | Long | はい | 識別子 | 変更不可 | |
lastSeenAlive | Long | 不可 | Sumo Logic サービスがアクティブなハートビートを Collector から最後に受信した時刻 (エポック時刻からのミリ秒で指定)。 | 一時 | |
name | 文字列 | はい | Collector の名前。アカウント上で一意でなければなりません。 | 変更可 | |
sourceSyncMode | 文字列 | 不可 | UI | Installed Collector の場合に、Collector がローカル Source 設定管理 (JSON ファイル) を使用するか、クラウド管理 (UI ) を使用するかの指定。 |
変更可JSON に割り当てるには、「既存 Collector および Source のローカル設定ファイル管理」を参照してください。 |
timeZone | 文字列 | 不可 | Null | Collector のタイム ゾーン。指定できる値については、この Wikipedia 記事の「TZ」の列を参照してください。 | 変更可 |
targetCpu | Long | 不可 | Null | CPU 利用率がこのしきい値を超えると、Collector は取り込み速度をスローダウンして、CPU 利用率を下げます。 現時点では、ローカルおよびリモート ファイル Source のみがサポートされます。 値は、整数のパーセント値で指定します。Collector は、使用する最大 CPU リソースの量を 20% に制限します。 詳細については、「Collector が使用する CPU ターゲットの設定」を参照してください。 |
変更可 |
以下の表に、Installed Collector 専用の応答フィールドを示します。
パラメータ | タイプ | 必須 | 説明 | アクセス |
osName | 文字列 | はい | Collector がインストールされている OS の名前。 | 変更不可 |
osVersion | 文字列 | はい | Collector がインストールされている OS のバージョン。 | 変更不可 |
osArch | はい | Collector がインストールされている OS のアーキテクチャ。 | 変更不可 | |
osTime | Long | はい | Collector が稼動している累積時間 (ミリ秒)。 | 変更不可 |
GET メソッド
Collector のリスト
Collector のリストを取得します。制限とオフセットを指定することもできます。
メソッド: GET Path: /collectors
パラメータ | タイプ | 必須 | デフォルト | 説明 |
filter | 文字列 | 不可 | すべての Collector | 次のいずれかのフィルタ タイプを使用して、返される Collector を絞り込みます。installed 、hosted 、dead 、alive 。 |
limit | 整数 | 不可 | 1000 | 返す Collector の最大数。 |
offset | 整数 | 不可 | 0 | Collector リストのオフセット |
例
この例では、limit=10
と指定することで応答を 10 件に制限しています。
リクエスト:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors?limit=10
応答:
{ "collectors":[ { "id":2, "name":"OtherCollector", "collectorType":"Installable", "alive":true, "links":[ { "rel":"sources", "href":"/v1/collectors/2/sources" } ], "collectorVersion":"19.33-28", "ephemeral":false, "description":"Local Windows Collection", "osName":"Windows 7", "osArch":"amd64", "osVersion":"6.1", "category":"local" }, ... ] }
オフライン Collector のリスト
指定した日数より前の最後の状態が alive であった Installed Collector のリストを取得します。制限とオフセットを指定することもできます。
メソッド: GET Path: /collectors/offline
パラメータ | タイプ | 必須 | デフォルト | 説明 |
aliveBeforeDays | 整数 | 不可 | 100 | Collector がオフラインである最小日数。 1 日以上を指定する必要があります。 |
limit | 整数 | 不可 | 1000 | 返す Collector の最大数。 |
offset | 整数 | 不可 | 0 | Collector リストのオフセット |
例
次の例では、aliveBeforeDays=10
の設定により、オフラインである期間が 10 日以上の Installed Collector のリストが返されます。
リクエスト:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10
応答:
{ "collectors":[{ "id":101622144, "name":"My Installed Collector", "timeZone":"Etc/UTC", "fields":{ "_budget":"test_budget" }, "links":[{ "rel":"sources", "href":"/v1/collectors/101622144/sources" }], "ephemeral":false, "targetCpu":-1, "sourceSyncMode":"UI", "collectorType":"Installable", "collectorVersion":"19.162-12", "osVersion":"10.12.6", "osName":"Mac OS X", "osArch":"x86_64", "lastSeenAlive":1521143016128, "alive":false }] }
ID による Collector の取得
指定された識別子を持つ Collector を取得します。
メソッド: GET Path: /collectors/[id]
パラメータ | タイプ | 必須 | デフォルト | 説明 |
id | 整数 | はい | NA | Collector の一意の識別子。 |
例
この例では、ID が 25 の Collector を取得しています。
リクエスト:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/25
応答:
{ "collector":{ "id":25, "name":"dev-host-1", "timeZone":"UTC", "ephemeral":false, "sourceSyncMode":"Json", "collectorType":"Installable", "collectorVersion":"19.162-12", "osVersion":"3.13.0-92-generic", "osName":"Linux", "osArch":"amd64", "lastSeenAlive":1471553524302, "alive":true } }
名前による Collector の取得
メソッド: GET Path: /collectors/name/[name]
パラメータ | タイプ | 必須 | デフォルト | 説明 |
name | 文字列 | はい | NA | Collector の名前。 |
ルール
;
、/
、%
、\
などの特殊文字を含む名前は、URL エンコードされる場合であってもサポートされません。- 名前内のスペースは、URL エンコードされる場合はサポートされます。URL エンコードされるスペース文字は
%20
です。たとえば、Collector の名前がStaging Area
であれば、https://api.sumologic.com/api/v1/collectors/name/Staging%20Area
のようにエンコードされます。 - 名前にピリオド
.
が含まれる場合は、リクエスト URL の末尾にスラッシュ/
を付ける必要があります。たとえば、Collector の名前がStaging.Area
であれば、https://api.sumologic.com/api/v1/collectors/name/Staging.Area/
のように指定する必要があります。
例
この例では、名前が test である Collector を取得しています。
リクエスト:
curl -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/name/test
応答:
{ "collector":{ "id":31, "name":"test", "timeZone":"UTC", "ephemeral":false, "sourceSyncMode":"Json", "collectorType":"Installable", "collectorVersion":"19.162-12", "osVersion":"3.13.0-92-generic", "osName":"Linux", "osArch":"amd64", "lastSeenAlive":1471553524302, "alive":true } }
POST メソッド
Hosted Collector の作成
POST メソッドで JSON ファイルを指定することで、新しい Hosted Collector を作成できます。必須パラメータについては、上記の表「応答フィールド」を参照してください。新規の Hosted Collector を作成する際には、id フィールドは指定しないでください。
メソッド: POST Path: /collectors
例
この例では、JSON ファイルにパラメータを指定して新規の Hosted Collector を作成しています。
リクエスト:
curl -u '<accessId>:<accessKey>' -X POST -H "Content-Type: application/json" -T hosted_collector.json https://api.sumologic.com/api/v1/collectors
リクエスト JSON (hosted_collector.json):
{ "collector":{ "collectorType":"Hosted", "name":"My Hosted Collector", "description":"An example Hosted Collector", "category":"HTTP Collection", "fields": { "_budget":"test_budget" } } }
応答:
{ "collector":{ "id":102087219, "name":"My Hosted Collector", "description":"An example Hosted Collector", "category":"HTTP Collection", "timeZone":"UTC", "fields":{ "_budget":"test_budget" }, "links":[{ "rel":"sources", "href":"/v1/collectors/102087219/sources" }], "collectorType":"Hosted", "collectorVersion":"", "lastSeenAlive":1536618284387, "alive":true }
PUT メソッド
Collector の更新
PUT メソッドで JSON ファイルを指定することで、既存の Collector を更新できます。利用できるパラメータについては、上記の表「応答フィールド」を参照してください。JSON リクエスト ファイルでは、すべての必須フィールドの値を指定する必要があります。変更不可のフィールドには、現在の値を指定しなければなりません。これは、HTTP 1.1 RFC-2616 セクション 9.6 の規則によるものです。
Collector を更新する際には、先行する GET リクエストのヘッダに返された ETag を If-Match ヘッダに指定する必要があります。
メソッド: PUT Path: /collectors/[id]
パラメータ | タイプ | 必須 | デフォルト | 説明 |
id | 整数 | はい | NA | Collector の ID。 |
例
この例では、Collector を更新して ephemeral パラメータを true に変更しています。
まず、GET リクエストで -v フラグを指定して、ETag ヘッダの値を取得します。
最初の GET リクエスト:
curl -v -u '<accessId>:<accessKey>' -X GET https://api.sumologic.com/api/v1/collectors/15
最初の GET 応答:
< HTTP/1.1 200 OK < ETag: "f58d12c6986f80d6ca25ed8a3943daa9" ... { "collector":{ "id":15, "name":"dev-host-1", "timeZone":"UTC", "ephemeral":false, "sourceSyncMode":"Json", "collectorType":"Installable", "collectorVersion":"19.162", "osVersion":"3.13.0-92-generic", "osName":"Linux", "osArch":"amd64", "lastSeenAlive":1471553974526, "alive":true } * Connection #0 to host api.sumologic.com left intact
次に、Collector の JSON 属性を必要に応じて修正し (この例では ephemeral パラメータを true に変更します)、上記で取得した ETag を If-Match ヘッダに指定した PUT リクエストを使用します。
リクエスト:
curl -u '<accessId>:<accessKey>' -X PUT -H "Content-Type: application/json" -H "If-Match: \"f58d12c6986f80d6ca25ed8a3943daa9\"" -T updated_collector.json https://api.sumologic.net/api/v1/collectors/15
リクエスト JSON (updated_collector.json):
{ "collector":{ "id":15, "name":"dev-host-1", "timeZone":"UTC", "ephemeral":true, "sourceSyncMode":"Json", "collectorType":"Installable", "collectorVersion":"19.162", "osVersion":"3.13.0-92-generic", "osName":"Linux", "osArch":"amd64", "lastSeenAlive":1471553974526, "alive":true } }
応答:
{ "collector":{ "id":15, "name":"dev-host-1", "timeZone":"UTC", "ephemeral":true, "sourceSyncMode":"Json", "collectorType":"Installable", "collectorVersion":"19.162", "osVersion":"3.13.0-92-generic", "osName":"Linux", "osArch":"amd64", "lastSeenAlive":1471554424736, "alive":true } }
DELETE メソッド
ID による Collector の削除
DELETE メソッドは、既存の Collector を削除します。
メソッド: DELETE Path: /collectors/[id]
パラメータ | タイプ | 必須 | デフォルト | 説明 |
id | 整数 | はい | NA | Collector の一意の識別子。 |
この例では、ID が 15 の Collector を削除しています。
リクエスト:
curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/15
応答: 応答に本文はなく、200 OK の応答コードのみが返されます。
オフライン Collector の削除
指定した日数より前の最後の状態が alive であった Installed Collector を削除します。
メソッド: DELETE Path: /collectors/offline
パラメータ | タイプ | 必須 | デフォルト | 説明 |
aliveBeforeDays | 整数 | 不可 | 100 | Collector がオフラインである最小日数。 1 日以上を指定する必要があります。 |
例
次の例では、aliveBeforeDays=10
の設定により、オフラインである期間が 10 日以上の Installed Collector がすべて削除されます。
リクエスト:
curl -u '<accessId>:<accessKey>' -X DELETE https://api.sumologic.com/api/v1/collectors/offline?aliveBeforeDays=10
応答:
応答に本文はなく、200 OK の応答とメッセージ [The delete task has been initiated (削除タスクが開始されました)] のみが返されます。ステータスを調べるには、GET リクエストを実行し、Collector が削除されているかどうかを確認します。
エラー コードとメッセージ
コード | メッセージ |
BadRequestCollectorId | リクエスト本文に無効な Collector ID が含まれています。 |
CannotModifyCollector | 指定された Collector を修正する権限がありません。 |
CollectorDescriptionTooLong | 説明は 1024 文字以内で指定してください。 |
CollectorNameTooLong | 名前は 128 文字以内で指定してください。 |
createValidationError | 指定された ID が無効です。 |
DuplicateResourceName | 同じ名前のリソースがすでに存在します。 |
InvalidCollector | 指定された Collector ID が無効です。 |
InvalidCollectorType | リクエストされた操作に対して Collector タイプが無効です。 |