Defender for Cloud アプリ REST API
この記事では、HTTPS を使用して Defender for Cloud Apps を操作する方法について説明します。
Microsoft Defender for Cloud Apps API を使用すると、REST API エンドポイントを通じて Defender for Cloud Apps にプログラムからアクセスできます。 アプリケーションでは、API を使用して、Defender for Cloud Apps のデータとオブジェクトに対する読み取りと更新の操作を実行できます。 たとえば、Defender for Cloud Apps API では、ユーザー オブジェクトに対する次の一般的な操作がサポートされています。
- Cloud Discovery のログ ファイルをアップロードします
- ブロック スクリプトを生成します
- アクティビティとアラートを一覧表示する
- アラートを無視または解決します
API URL の構造
Defender for Cloud Apps API を使用するには、最初にテナントから API の URL を取得する必要があります。 API URL には次の形式を使用します: https://<portal_url>/api/<endpoint>。
テナントの Defender for Cloud Apps API URL を取得するには、次の手順を実行します。
Microsoft Defender Portal で、[設定] を選択します。 次に、[クラウド アプリ] を選択します。 [システム] で [バージョン情報] を選択します。
Defender for Cloud Apps のバージョン情報画面で、API URL を確認できます。
API URL を取得したら、そこに /api サフィックスを追加して API URL を取得します。 たとえば、ポータルの URL が https://mytenant.us2.contoso.com の場合、API URL は https://mytenant.us2.portal.cloudappsecurity.com/api になります。
API トークン
Defender for Cloud Apps では、サーバーへのすべての API 要求のヘッダーで、API トークンを指定する必要があります。次に例を示します。
Authorization: Token <your_token_key>
ここでは <your_token_key> は個人用 API トークンです。
API トークンの詳細については、「API トークンの管理」を参照してください。
API トークン - 例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint"
サポートされているアクション
次の表ではサポートされているアクションについて説明します。
| リソース | HTTP 動詞 | URI ルート |
|---|---|---|
| 活動 | GET または POST | /api/v1/activities/ |
| 警告 | GET または POST | /api/v1/alerts/ |
| データ エンリッチメント | GET、POST、または DELETE | /api/subnet/ |
| エンティティ | GET または POST | /api/v1/entities/ |
| Files | GET または POST | /api/v1/files/ |
ここで、リソース は関連エンティティのグループを表します。
サポートされているフィールドの種類は何ですか？
次の表に、サポートされているフィールドの種類について説明します。
| フィールド | 説明 |
|---|---|
| string | テキスト文字列 |
| boolean | true/false を表すブール値 |
| integer | 32 ビット符号付き整数 |
| timestamp | エポックからの経過ミリ秒 |
タイムスタンプ
Defender for Cloud Apps API によって言及されるタイムスタンプは、Unix のタイムスタンプ (ミリ秒) を指しています。 このタイムスタンプは、1970-01-01 0:00:00 からのミリ秒数によって決まります。 get-date PowerShell コマンドレットを使用して、日付をタイムスタンプに変換できます。
制限
要求に制限パラメーターを指定することで、要求を制限することができます。
次のメソッドは、制限パラメーターの指定にサポートされています。
- URL エンコードされたもの (
Content-Type: application/x-www-form-urlencodedヘッダーあり) - データを形成する
- JSON 本文 (
Content-Type: multipart/form-dataと適切な境界ヘッダーあり)
Note
- 制限を指定しない場合、既定で 100 に設定されます。
- API トークンを使用して行われたすべての要求に対する応答は、最大 100 アイテムに制限されます。
- すべての API 要求のスロットリング制限は、1 テナントに付き 1 分あたり 30 要求です。
フィルター
結果の数が多い場合は、フィルターを使用して要求を微調整すると便利です。 このセクションでは、フィルターの構造と、フィルターで使用できる演算子について説明します。
構造
一部の API エンドポイントでは、クエリ実行時のフィルターがサポートされています。 関連するセクションには、使用可能なすべてのフィルター可能なフィールドとそのリソースでサポートされている演算子の一覧が記載されたリファレンスが表示されます。
ほとんどのフィルターでは、強力なクエリを提供するために複数の値がサポートされています。 フィルターと演算子を組み合わせる場合は、フィルター間の論理演算子として AND を使用します。
フィルター - 例
curl -XGET -H "Authorization:Token <your_token_key>" "https://<tenant_id>.<tenant_region>.portal.cloudappsecurity.com/api/example-endpoint" -d '{
"filters": {
"some.field": {
"eq": ["value1", "value2"],
"isset": true
},
"some.field2": {
"gte": 5
}
},
"skip": 5,
"limit": 10
}'
演算子
Note
すべての演算子がすべてのフィルターと互換性があるわけではありません。
次の表に、サポートされている演算子について説明します。
| 演算子 | 応答の種類 | 説明 |
|---|---|---|
| contains | 文字列のリスト | 指定した文字列のいずれかを含むすべての関連レコードを返します |
| deq | 値の一覧 | 指定された値と等しくない 1 つの値を含むすべてのレコードを返します |
| descendantof | 値の一覧 | 値またはそれらの子孫に一致するすべての関連レコードを返します |
| doesnotstartwith | 文字列のリスト | 指定された各文字列で始まれていないすべての関連レコードを返します |
| 指定の値で終わる | 文字列のリスト | 指定された文字列の 1 つで終わる関連するすべてのレコードを返します |
| eq | 値の一覧 | 指定された値のいずれかを含むすべての関連レコードを返します |
| gt | 単一値 | 指定された値より大きい値を持つすべてのレコードを返します |
| gte | 単一値 | 指定された値以上の値を持つすべてのレコードを返します |
| gte_ndays | 数値 | N 日前より後の日付であるすべてのレコードを返します |
| isnotset | boolean | "true" に設定すると、指定したフィールドに値がないすべての関連レコードを返します |
| isset | boolean | "true" に設定すると、指定したフィールドに値があるすべての関連レコードを返します |
| lt | 単一値 | 指定した値より小さい値を持つすべてのレコードを返します |
| lte | 単一値 | 指定された値以下の値を持つすべてのレコードを返します |
| lte_ndays | 数値 | N 日前より前の日付であるすべてのレコードを返します |
| ncontains | 文字列のリスト | 指定した文字列のいずれかを含まないすべての関連レコードを返します |
| ndescendantof | 値の一覧 | 値またはそれらの子孫と一致しないすべての関連レコードを返します |
| neq | 値の一覧 | 指定されたすべての値が含まれていないすべての関連レコードを返します |
| 範囲 | "start" (開始) フィールドと "end" (終了) フィールドを含むオブジェクトの一覧 | 指定した範囲のいずれか内のすべてのレコードを返します |
| startswith | 文字列のリスト | 指定された文字列の 1 つから始まる関連するすべてのレコードを返します |
| startswithsingle | string | 指定された文字列で始まる関連するすべてのレコードを返します |
| text | string | すべてのレコードのフルテキスト検索を実行します |
次のステップ
問題が発生した場合は、ここにお問い合わせください。 お使いの製品の問題について支援やサポートを受けるには、サポート チケットを作成してください。