Defender for Cloud Apps REST API

[アーティクル]
11/28/2024

この記事では、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 では、ユーザーオブジェクトに対して次の一般的な操作がサポートされています。

クラウド検出用のログファイルをアップロードする
ブロックスクリプトを生成する
アクティビティとアラートを一覧表示する
アラートを無視または解決する

API URL 構造体

Defender for Cloud Apps API を使用するには、まずテナントから API URL を取得する必要があります。 API URL は、次の形式を使用します: https://<portal_url>/api/<endpoint>。

テナントのDefender for Cloud Apps API URL を取得するには、次の手順を実行します。

Microsoft Defender ポータルで、[設定] を選択します。次に、[ Cloud Apps] を選択します。 [ システム] で、[ バージョン情報] を選択します。
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/
Entities	GET または POST	/api/v1/entities/
ファイル	GET または POST	/api/v1/files/

ここで、Resource は関連エンティティのグループを表します。

サポートされているフィールドの種類は何ですか?

次の表では、サポートされているフィールド型について説明します。

フィールド	説明
string	テキスト文字列
ブール値	true/false を表すブール値
integer	32 ビットの符号付き整数
timestamp	エポック以降のミリ秒

タイムスタンプ

Defender for Cloud Apps API のタイムスタンプに関する言及は、Unix タイムスタンプ (ミリ秒単位) を参照します。このタイムスタンプは、1970-01-01 0:00:00 以降のミリ秒数によって決まります。 get-date PowerShell コマンドレットを使用して、日付をタイムスタンプに変換できます。

制限

要求に limit パラメーターを指定することで、要求を制限できます。

limit パラメーターを指定するために、次のメソッドがサポートされています。

URL エンコード ( Content-Type: application/x-www-form-urlencoded ヘッダー付き)
フォームデータ
JSON 本文 ( Content-Type: multipart/form-data と適切な境界ヘッダー)

注:

制限が指定されていない場合は、既定値の 100 が設定されます。
API トークンを使用して行われたすべての要求に対する応答は、最大 100 項目に制限されます。
すべての API 要求のスロットル制限は、テナントあたり 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
}'

演算子

注:

すべての演算子がすべてのフィルターと互換性があるわけではありません。

次の表では、サポートされている演算子について説明します。

オペレーター	応答の種類	説明
contains	文字列のリスト	指定された文字列のいずれかを含むすべての関連レコードを返します
deq	値の一覧	指定された値と等しくない 1 つの値を含むすべてのレコードを返します
descendantof	値の一覧	値またはそれらの子孫に一致するすべての関連レコードを返します
doesnotstartwith	文字列のリスト	指定された各文字列で始まるすべての関連レコードを返します
endswith	文字列のリスト	指定された文字列の 1 つで終わるすべての関連レコードを返します
eq	値の一覧	指定された値のいずれかを含むすべての関連レコードを返します
gt	1 つの値	指定された値より大きい値を持つすべてのレコードを返します
gte	1 つの値	指定された値以上の値を持つすべてのレコードを返します
gte_ndays	番号	N 日前より後の日付のすべてのレコードを返します
isnotset	ブール値	"true" に設定すると、指定したフィールドに値がないすべての関連レコードが返されます
isset	ブール値	"true" に設定すると、指定したフィールドに値を持つ関連するすべてのレコードが返されます
lt	1 つの値	値が指定された値より小さいすべてのレコードを返します
lte	1 つの値	指定された値以下の値を持つすべてのレコードを返します
lte_ndays	番号	N 日前より前の日付のすべてのレコードを返します
ncontains	文字列のリスト	指定された文字列のいずれかが含まれていないすべての関連レコードを返します
ndescendantof	値の一覧	値またはそれらの子孫と一致しない関連するすべてのレコードを返します
neq	値の一覧	指定されたすべての値が含まれていないすべての関連レコードを返します
range	"start" フィールドと "end" フィールドを含むオブジェクトの一覧	指定された範囲内のすべてのレコードを返します
startswith	文字列のリスト	指定された文字列の 1 つから始まるすべての関連レコードを返します
startswithsingle	string	指定された文字列で始まるすべての関連レコードを返します
テキスト	string	すべてのレコードのフルテキスト検索を実行します

次の手順

API 認証

問題が発生した場合は、ここにお問い合わせください。製品の問題に関するサポートまたはサポートを受けるためには、サポートチケットを開いてください。

次の方法で共有