メインコンテンツまでスキップ
Sumo Logic Japanese

Collector API メソッドと例

Collector 管理 API により、HTTP エンドポイントから Collector や Source を管理できます。このトピックでは、Collector API のパラメータとメソッドについて説明し、エラー コードのリストを示します。

詳細については以下のトピックを参照してください。

レート制限

  • ユーザからのすべての API コールには、最大で毎秒 4 件 (毎分 240 件) の API リクエストというレート制限が適用されます。
  • また、同じアクセス キーには、どの API エンドポイントでも最大で同時に 10 件のリクエストというレート制限が適用されます。

このレートを超えると、rate limit exceeded (レート制限超過) の 429 ステータス コードが返されます。

応答フィールド 

以下の表に、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 を絞り込みます。

installedhosteddeadalive
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 タイプが無効です。
  • この記事は役に立ちましたか?