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

コレクタ API メソッドと例

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

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

Rate limiting

  • A rate limit of four API requests per second (240 requests per minute) applies to all API calls from a user.
  • A rate limit of 10 concurrent requests to any API endpoint applies to an access key.

If a rate is exceeded, a rate limit exceeded 429 status code is returned.

応答フィールド 

以下の表に、インストール済みコレクタとホスト型コレクタの API 応答フィールドを示します。

パラメータ タイプ 必須 デフォルト 説明 アクセス
alive ブール はい   Sumo がハートビート メッセージを 15 秒おきに受信すると、コレクタは動作中であると判断されます。ハートビート メッセージが 30 分間受信できないと、このパラメータは false になります。 一時
カテゴリ 文字列 不可 Null データの検索時にメタデータとして使用されるコレクタのカテゴリ。 変更可
collectorType 文字列     コレクタ タイプ: Installableまたは Hosted 変更不可
collectorVersion 文字列 はい   インストールされているコレクタ ソフトウェアのバージョン。 一時
cutoffRelativeTime 文字列 不可   cutoffTimestamp の代わりに指定することで、現在時刻に対する相対オフセットを指定できます。例: "-1h""-1d""-1w" で、それぞれ 1 時間、1 日、1 週間前の時刻を指定します。  変更不可
cutoffTimestamp Long 不可 0 (すべてのデータを収集) エポック時刻からのミリ秒で指定したこのタイムスタンプ以降のファイルのみからデータを収集します。 変更可
description 文字列 不可 Null コレクタの説明。 変更可
ephemeral ブール はい   コレクタが ephemeral に指定されていると、操作が何も行われない状態が 12 時間続いた時点で削除されます。 変更可
hostName 文字列 不可 Null コレクタのホスト名。ホスト名は最大 128 文字です。 変更可
id Long はい   識別子 変更不可
lastSeenAlive Long 不可   Sumo Logic サービスがアクティブなハートビートをコレクタから最後に受信した時刻 (エポック時刻からのミリ秒で指定)。 一時
name 文字列 はい   コレクタの名前。アカウント上で一意でなければなりません。  変更可
sourceSyncMode 文字列 不可 UI インストール済みコレクタの場合に、コレクタがローカル ソース設定管理 (JSON ファイル) を使用するか、クラウド管理 (UI) を使用するかの指定。 config/user.propertiessyncSources を追加して正しい JSON ファイル (syncSources=/path/to/sources.json
 ) を指定した場合にのみ変更できます。変更はコレクタの再起動時に行われます。

Windows では、ファイル パス path:
syncSources=C:\\path\\to
sources.json を二重バックスラッシュで囲んで指定して、コレクタを再起動します。
 
API での変更ではなく、ローカル設定ファイルの使用をお勧めします。この方法の詳細については、既存コレクタおよびソースのローカル設定ファイル管理」を参照してください。
timeZone 文字列 不可 Null コレクタのタイム ゾーン。 変更可
targetCpu Long 不可 Null 指定した場合、CPU 利用率がこのしきい値を超えると、コレクタはデータの取り込みをスローダウンして、リソースの利用率を下げます。現時点では、ローカルおよびリモート ファイル ソースのみがサポートされます。関連情報。 変更可

 

以下の表に、インストール済みコレクタ専用の応答フィールドを示します。

パラメータ タイプ 必須 説明 アクセス
osName 文字列 はい コレクタがインストールされている OS の名前。 変更不可
osVersion 文字列 はい コレクタがインストールされている OS のバージョン。 変更不可
osArch   はい コレクタがインストールされている OS のアーキテクチャ。 変更不可
osTime Long はい コレクタが稼動している累積時間 (ミリ秒)。 変更不可

GET メソッド 

コレクタのリスト  

コレクタのリストを取得します。制限とオフセットを指定することもできます。

メソッド: GET Path: /collectors

パラメータ タイプ 必須 デフォルト 説明
limit 整数 不可 1000 返すコレクタの最大数。
offset 整数 不可 0 コレクタ リストのオフセット
例 

この例では、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"
      },
      ...
   ]
}

ID によるコレクタの取得 

指定された ID のコレクタを取得します。

メソッド: GET Path: /collectors/[id]

パラメータ タイプ 必須 デフォルト 説明
id 整数 はい NA コレクタの ID。
例 

この例では、ID が 25 のコレクタを取得しています。

リクエスト:

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
  }
}

POST メソッド

ホスト型コレクタの作成

 POST メソッドで JSON ファイルを指定することで、新しいホスト型コレクタを作成できます。必須パラメータについては、上記の表「応答フィールド」を参照してください。新規のホスト型コレクタを作成する際には、id フィールドは指定しないでください。

メソッド: POST Path: /collectors

この例では、JSON ファイルにパラメータを指定して新規のホスト型コレクタを作成しています。

リクエスト:

curl -u 'accessid:accesskey' -X POST -H "Content-Type: application/json" -T hosted_collector.json https://api.sumologic.com/api/v1/collectors

リクエスト JSON (host_metrics.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 メソッド 

コレクタの更新 

PUT メソッドで JSON ファイルを指定することで、既存のコレクタを更新できます。利用できるパラメータについては、上記の表「応答フィールド」を参照してください。JSON リクエスト ファイルでは、すべての必須フィールドの値を指定する必要があります。変更不可のフィールドには、現在の値を指定しなければなりません。これは、HTTP 1.1 RFC-2616 セクション 9.6 の規則によるものです。 

コレクタを更新する際には、先行する GET リクエストのヘッダに返された ETag を If-Match ヘッダに指定する必要があります。

メソッド: PUT Path: /collectors/[id]

パラメータ タイプ 必須 デフォルト 説明
id 整数 はい NA コレクタの ID。
例 

この例では、コレクタを更新して 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

次に、コレクタの 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 メソッド 

DELETE メソッドは、既存のコレクタを削除します。

メソッド: DELETE Path: /collectors/[id]

パラメータ タイプ 必須 デフォルト 説明
id 整数 はい NA コレクタの ID。

この例では、ID が 15 のコレクタを削除しています。

リクエスト:

curl -u 'accessid:accesskey' -X DELETE https://api.sumologic.com/api/v1/collectors/15

応答: 応答に本文はなく、200 OK の応答コードのみが返されます。

エラー コードとメッセージ  

コード メッセージ
BadRequestCollectorId リクエスト本文に無効なコレクタ ID が含まれています。
CannotModifyCollector 指定されたコレクタを修正する権限がありません。
CollectorDescriptionTooLong 説明は 1024 文字以内で指定してください。
CollectorNameTooLong 名前は 128 文字以内で指定してください。
createValidationError 指定された ID が無効です。
DuplicateResourceName 同じ名前のリソースがすでに存在します。
InvalidCollector 指定された コレクタ ID が無効です。
InvalidCollectorType リクエストされた操作に対してコレクタ タイプが無効です。
  • この記事は役に立ちましたか?