Netskope dataexportエンドポイント（イテレータエンドポイントとも呼ばれる）は、テナントログ情報を簡単に取得する方法を提供します。この記事では、このデータを利用する際のベストプラクティスについて説明します。Netskope 、可能な限り既存のクライアントを活用してSIEMを統合することを推奨します。 以下のソリューションのいずれかを使用してください。
- Netskope Cloud Exchange : ログシッパーモジュール: /en/ Netskope - Cloud Exchange .html
- Netskope Splunkテクニカルアドオン： https://apps.splunk.com/app/3808/
- Sumo Logic Netskope WebTx ソース: https://help.sumologic.com/docs/send-data/hosted-collectors/cloud-to-cloud-integration-framework/netskope-webtx-source/
上記のクライアントで不十分な場合は、NetskopeはPython SDKも提供しています。
- データエクスポートエンドポイント用のPython SDK https://pypi.org/project/netskopesdk/
イテレータのエンドポイントはどのように機能しますか？
Netskopeプラットフォームは、インデックスの使用を通じて、ウェブ フォーラムでよく見られるものを再現する簡素化された運用ワークフローを通じてログの消費を追跡します。 消費者がエンドポイントからデータページを要求すると、Netskopeは提供されたデータに関するインデックスを書き込むことで、要求されたデータを提供します。消費者が要求したデータページの処理を完了したら、次のデータページを要求するだけです。
各エンドポイントは独自のインデックス値を格納しており、その値はクエリ実行時にコンシューマーによって提供されます。これにより、複数のエンドポイントにわたるAPI呼び出しを容易に並列化して同時に実行することが可能になります。
注記
複数のコンシューマーが同じエンドポイントとインデックスを同時に利用することはサポートされておらず、コンシューマー上でデータが欠落する事態が発生する可能性があります。
イテレータクエリ構造
エンドポイントクエリの構造は非常に簡単に構築できます。
https://<tenant-URL>/api/v2/<endpoint>/?operation=<operation>&index=<index>
サポートされているイテレータ操作
epoch timestamp: エポック タイムスタンプが指定されている場合、このタイムスタンプから 1 時間のバッチでログの消費を開始するようにNetskopeエンドポイントに通知されます。 ログをさらに取得するには、 次の操作を実行する必要があります。next: 次の操作値は、 Netskopeエンドポイントからデータの次のページを要求します。resend: 消費者が提供されたデータページを処理できない場合、再送信操作は要求された最後のデータページを再試行します。
epoch timestampとnext操作はどちらもNetskopeに保存されているインデックスを更新しますが、 resend操作はインデックスを更新せずに前のページを要求します。
イテレータインデックス
イテレータのインデックス値は、コンシューマーから提供される文字列値です。 Netskopeによってページ値を格納するために使用されます。 データ消費に関する問題を回避するため、このインデックスは消費者ごとに固有のものであるべきです。消費者は、複数のエンドポイントにわたって同じインデックス値を安心して使用できます。
インデックス文字列は使う(使う)で、複数のシステムが丸太を引っ張っている場合に使われます。 例えば、使う デモ をインデックスにして、記録1から1000までプルします。 次に デモがログを引くときは、1001〜2000のログを1000回ずつ引っ張ります。
空欄のままにして2つのシステムがログを取得する場合、最初のシステムはログ1～1000を取得し、次に2番目のシステムがログを取得すると、1001～2000を取得します。これは最適とは言えません。
システム1（demo1）とシステム2（demo2）が同時にログを取得する場合、それぞれが1～1000の一意のインデックス文字列を取得します。 一意のインデックス文字列。
インデックスを使用しないと、「再利用される」可能性があります。 独自のインデックスを定義すれば、そのインデックス値を持つのは自分だけであり、レコードが失われることはないという保証が得られます。
ページサイズ
Netskope Iterator エンドポイントは、API 呼び出しごとに 10,000 レコード ページを提供します。
待ち時間
各イテレータクエリは、待機時間を秒単位で示します。この値は、API呼び出しで返されるデータ量に基づいて計算されます。
{
"ok": 1,
"result": [
{
}
],
"wait_time": 5
レート制限
429エラーメッセージを回避するために、レート制限を管理するレスポンスヘッダーを使用することをお勧めします。
- RateLimit-Limit: レート制限はエンドポイントごとに適用され、この値は1秒あたりに許可される回数を示します。
- RateLimit-Remaining: 429 エラーメッセージを生成する前に、インターバルがリセットされるまでにサポートされるクエリの数。
- RateLimit-Reset: レート制限がリセットされるまでの時間。この値は秒単位です。
HTTP/1.1 200 OK .... RateLimit-Limit: 4 RateLimit-Remaining: 1 RateLimit-Reset: 1 ...
レートを超過した場合、ヘッダーが拡張され、データペイロードにはクエリが429エラー応答を返した理由が記載されます。
- 再試行後：これは、クエリを再試行するまでの推奨待機時間です。この値の単位は秒です。
HTTP/1.1 429 Too Many Requests
...
RateLimit-Remaining: 0
RateLimit-Reset: 1
Retry-After: 1
RateLimit-Limit: 4
...
{
"message":"API rate limit exceeded"
}
例
ワークフローの例Netskopeが持つ最も古いレコードから開始して反復子エンドポイントを使用します。
operation=nextとインデックス値を使用してクエリを作成します。https://<tenant-URL>/api/v2/events/dataexport/events/alert?operation=next&index=demo
- JSONレスポンス内の
wait_time属性を確認してください。"wait_time": 5
- エンドポイントから次のページのデータを要求します。
https://<tenant-URL>/api/v2/events/dataexport/events/alert?operation=next&index=demo
- 手順2と3を繰り返してください。
エラー応答コード
| エラーコード | ユーザーによる操作が必要です | 注記 |
|---|---|---|
| 403 | はい | API V2トークンが有効なエンドポイントに関連付けられており、有効期限が切れていないことを確認してください。再試行は、ガイドラインに従ってトークンの問題を解決した後にのみ問題を解決します。 |
| 409 | いいえ | 同時実行競合が発生しており、現時点ではリクエストを処理できません。DataExport API V2 エンドポイントは、同じイテレータインデックスを使用して同じイベントタイプを同時にダウンロードすることをサポートしていません。クライアントは、イベントを取得するロジックがシングルスレッドであることを検証する必要があります。 |
| 429 | いいえ | 同一テナントから同一エンドポイントへのアクセス要求が多すぎます。クライアントは、429 エラーを回避するためにレート制限を遵守することが求められ、レスポンス ヘッダーの一部として、ratelimit-reset ヘッダーにリセット時刻が含まれます。クライアントは、429 エラーを回避するためにスリープ/待機 (ratelimit-reset) する必要があります。現在のレート制限は、エンドポイントあたり毎秒4リクエストです。 |
| 5xx | いいえ | Netskopeでは、以下のいずれかの理由により、一時的なサーバー障害が発生しています。
|
Client Status Iterator API を使用する
Netskope Client定期的にクライアントの状態をNetskopeバックエンドに送信し、テナントUIでクライアントのさまざまな側面を確認できるようにします。 例えば、ユーザーが開始した操作に関するステータス（有効化／無効化）、インストール／アップグレードのステータス、現在のトンネルのステータス（稼働中／停止中）などです。ユーザーは、テナントUIのデバイスページでクライアントのステータスログを確認できます。
Netskopeプラットフォームは、クライアント ステータス イテレータの使用を通じて、簡素化された運用ワークフローを通じてログの消費を追跡します。 利用者がエンドポイントからクライアントステータスイベントのページを要求すると、Netskopeは要求されたイベントを配信し、提供されたイベントの透かしを含むインデックスを書き込みます。消費者が要求したイベントページの処理を完了したら、次のページを要求するだけです。
クライアントステータスイテレータサービスは、ストリーミングAPIと以下の管理APIを提供します。
- イテレータ作成API：新しいイテレータを作成できます。イベントログのリクエストを送信する前に、このAPIを呼び出してください。
- イテレータステータス確認API：イテレータの作成が完了したかどうかを確認できます。
- イテレータ削除API：既存のイテレータを削除できます。一般的に、これは 特定のイベントタイプのイテレータの名前を変更する必要がある場合です。
- イベントフェッチAPI：イテレータからイベントログをリクエストできます。応答はCSV形式で返されます。
ワークフロー
新しい API を使用してクライアント ステータス イベントをリクエストする方法の例を次に示します。
- クライアントのステータスイベント用のイテレータを作成するためのイテレータAPIを作成します。
POST https://my_test_tenant/api/v2/dataexport/iterator/my_test_index?eventtype=clientstatus
- イテレータの状態を確認するAPIを使用して、イテレータの作成状態を、イテレータの状態が準備完了になるまで確認します。
GET https://my_test_tenant/api/v2/dataexport/iterator/my_test_index?
- イテレータからイベントを要求するためのイベントフェッチAPI。
Get https://my_test_tenant/api/v2/dataexport/iterator/my_test_index/events?operation=next
- レスポンスヘッダーの wait_time 属性を確認し、それに応じて十分な時間待機します。例: “wait_time”: 1
- イテレータイベントリクエストAPIは、イテレータからイベントをリクエストするためのものです。
Get https://my_test_tenant/api/v2/dataexport/iterator/my_test_index/events?operation=next
- 手順4と5を繰り返してください。
API制限
- テナントごとに許可されるクライアントステータスイテレータは1つのみとします。
- イテレータの作成または削除の同時リクエストはサポートされておらず、リクエストの失敗につながる可能性があります。
- イテレータサービスは、最新のイベントログを高速でストリーミングするように設計されています。一定期間より古いイベントログのみをリクエストできます。期限内にリクエストされない場合、それより古いイベントは自動的に削除されます。クライアントステータスイテレータの保持期間は7日間です。
- 同一イテレータに対する同時イベント取得リクエストはサポートされておらず、リクエストは失敗します。
- 複数のコンシューマーが同じイテレータから同時にイベントログを要求することはサポートされておらず、コンシューマー上でデータが欠落しているように見える可能性があります。