Office 365 マネージメント アクティビティ API のリファレンス

Office 365管理アクティビティ API を使用して、Office 365およびMicrosoft Entra アクティビティ ログからユーザー、管理者、システム、ポリシーのアクションとイベントに関する情報を取得します。

Office 365のアクションとイベントを使用し、監査ログとアクティビティ ログをMicrosoft Entraして、監視、分析、およびデータの視覚化を提供するソリューションを作成できます。 このソリューションにより、企業はそのコンテンツに対して実行されたアクションの可視性を向上させることができます。 これらのアクションとイベントは、Office 365 アクティビティ レポートからも入手できます。 詳細については、「Search the audit log in the Microsoft 365 (Microsoft 365 での監査ログの検索)」を参照してください。

Office 365 管理アクティビティ API は、REAT Web サービスの 1 つであり、任意の言語と、HTTPS および X.509 証明書をサポートするホスト環境を用いて、ソリューションの開発に使用できます。 API は、認証と承認にMicrosoft Entra IDと OAuth2 プロトコルに依存しています。 アプリケーションから API にアクセスするには、まずMicrosoft Entra IDに API を登録し、適切なアクセス許可で構成する必要があります。 これにより、アプリケーションで、API を呼び出すために必要な OAuth2 アクセス トークンを要求できます。 詳細については、「Office 365 管理 API の使用を開始する」を参照してください。。

Office 365 管理アクティビティ API で返されるデータの詳細情報については、「Office 365 管理アクティビティ API のスキーマ」を参照してください。

Office 365 管理アクティビティ API の操作

Office 365 管理アクティビティ API は、アクションとイベントを、タイプ別およびコンテンツのソース別に分類されたテナント固有コンテンツ blob に集約します。 現時点では、次のコンテンツ タイプがサポートされています。

• Audit.AzureActiveDirectory

• Audit.Exchange

• Audit.SharePoint

• Audit.General (上記のコンテンツ タイプに含まれない、その他すべてのワーク ロードが含まれます)

• DLP.All (すべてのワークロードの DLP イベントのみ)

イベントおよびこれらのコンテンツ タイプに関連付けられているプロパティの詳細については、「Office 365 管理アクティビティ API のスキーマ」を参照してください。

テナントのコンテンツ BLOB の取得を開始するには、まず目的のコンテンツ タイプへのサブスクリプションを作成します。 複数のテナントのコンテンツ blob を取得する場合は、テナントごとに 1 つずつ、目的の各コンテンツ タイプの複数のサブスクリプションを作成します。

サブスクリプションを作成したら、ダウンロードできる新しいコンテンツ blob を発見するために定期的にポーリングできます。または Webhook エンドポイントをサブスクリプションに登録して、新しいコンテンツ blob が入手可能になったときにそのエンドポイントで通知を受け取ることができます。

アクティビティ API の操作

すべての API 操作のスコープは単一のテナントであり、API のルート URL にはテナント コンテキストを示すテナント ID が含まれています。 テナント ID は、GUID です。 GUID を取得する方法の詳細については、「Office 365 管理 API の使用を開始する」を参照してください。

Webhook に送信される通知にはテナント ID が含まれるため、同じ Webhook を使用してすべてのテナントの通知を受け取ることができます。

使用する API エンドポイントの URL は、組織の Microsoft 365 または Office 365 のサブスクリプション プランの種類に基づいています。

Enterprise プラン

https://manage.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}

GCC 政府機関向けプラン

https://manage-gcc.office.com/api/v1.0/{tenant_id}/activity/feed/{operation}

GCC High 政府機関向けプラン

https://manage.office365.us/api/v1.0/{tenant_id}/activity/feed/{operation}

DoD 政府機関向けプラン

https://manage.protection.apps.mil/api/v1.0/{tenant_id}/activity/feed/{operation}

すべての API 操作には、Microsoft Entra IDから取得したアクセス トークンを含む Authorization HTTP ヘッダーが必要です。 アクセス トークンのテナント ID は API のルート URL のテナント ID と一致する必要があり、アクセス トークンには ActivityFeed.Read 要求が含まれている必要があります (これは、アプリケーション用に構成したアクセス許可 [organizationのアクティビティ データの読み取り] に対応Microsoft Entra ID)。

Authorization: Bearer eyJ0e...Qa6wg

アクティビティ API は、次の操作をサポートします。

• サブスクリプションの開始。テナントの通知の受け取りとアクティビティ データの取得を開始します。

• サブスクリプションの停止。テナントのデータの取得を中止します。

• 現在のサブスクリプションのリストの作成

• 利用可能なコンテンツのリストの作成。これには対応するコンテンツの URL も含まれます。

• 通知の受け取り。この通知は新しいコンテンツが利用可能になったときに Webhook により送信されます。

• コンテンツの取得。コンテンツ URL を使用して実行します。

• 通知のリストを作成。この通知は Webhook によって送信されます。

• リソースのフレンドリ名の取得。GUID で識別されるデータ フィード内のオブジェクトに関して実行します。

サブスクリプションの開始

この操作は、指定したコンテンツ タイプのサブスクリプションを開始します。 指定したコンテンツ タイプのサブスクリプションが既に存在する場合、この操作は次の目的で実行します。

• アクティブな Webhook のプロパティを更新します。

• 失敗通知数の超過により無効になった Webhook を有効にします。

• 新しい (または null の) 有効期限日を指定することで、有効期限切れの Webhook を再度有効にします。

• Webhook を削除します。

要求のサンプル

POST {root}/subscriptions/start?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Content-Type: application/json; utf-8
Authorization: Bearer eyJ0e...Qa6wg

{
    "webhook" : {
        "address": "https://webhook.myapp.com/o365/",
        "authId": "o365activityapinotification",
        "expiration": ""
    }
}

応答のサンプル

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

{
    "contentType": "Audit.SharePoint",
    "status": "enabled",
    "webhook": {
        "status": "enabled",
        "address":  "https://webhook.myapp.com/o365/",
        "authId": "o365activityapinotification",
        "expiration": null
    }
}

Webhook の検証

/Start 操作が呼び出され、Webhook が指定されると、アクティブ リスナーが通知を受け入れて処理できることを検証するために、指定された Webhook アドレスに検証通知が送信されます。 HTTP 200 OK 応答が返信されない場合は、サブスクリプションは作成されません。 または、Webhook を既存のサブスクリプションに追加するために /start が呼び出されているものの、HTTP 200 OK の応答が返信されない場合は、Webhook は追加されず、サブスクリプションは変更されません。

要求のサンプル

POST {webhook address}
Content-Type: application/json; charset=utf-8
Webhook-AuthID: (webhook authId, if provided)
Webhook-ValidationCode: (random opaque string)

{
    "validationCode": (random opaque string, same as header)
}

応答のサンプル

HTTP/1.1 200 OK

サブスクリプションの停止

この操作は、指定したコンテンツ タイプのサブスクリプションを停止します。

サブスクリプションが停止すると、通知は受信されなくなり、利用可能なコンテンツを取得できなくなります。 サブスクリプションが後で再起動された場合は、その時点から新しいコンテンツにアクセスできます。 サブスクリプションが停止して再開するまでの間に使用可能であったコンテンツは取得できません。

要求のサンプル

POST {root}/subscriptions/stop?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

応答のサンプル

HTTP/1.1 200 OK

現在のサブスクリプションのリストの作成

この操作は、現在のサブスクリプションのコレクションと、関連する Webhook を返します。

要求のサンプル

GET {root}/subscriptions/list?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

応答のサンプル

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType" : "Audit.SharePoint",
        "status": "enabled",
        "webhook": {
            "status": "enabled",
            "address": "https://webhook.myapp.com/o365/",
            "authId": "o365activityapinotification",
            "expiration": null
        }
    },

    ...

    {
        "contentType": "Audit.Exchange",
        "webhook": null
    }
]

利用可能なコンテンツのリストの作成

この操作は、指定したコンテンツ タイプの、現在取得可能なコンテンツのリストを作成します。 コンテンツは、複数のデータセンターにある複数のサーバーから収集されたアクションとイベントの集約です。 コンテンツは、集約が利用可能になった順にリストされされますが、集約内のイベントとアクションは必ずしも連続的にはなりません。 サブスクリプションの状態が無効である場合は、エラーが返されます。

要求のサンプル

GET {root}/subscriptions/content?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

応答のサンプル

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z"
    },
    ...
]

改ページ

ある時間範囲の利用可能なコンテンツのリストを作成する場合、返される結果の数は、応答のタイムアウトを防ぐために制限されます。 指定の時間範囲内に 1 つの応答で返せるよりもより多くの結果がある場合、結果は切り捨てられ、次ページの結果を取得するために使用する URL を示すヘッダーが応答に追加されます。 URL には、元の要求で指定されたのと同じ startTime パラメーターと endTime パラメーターと、次のページの内部 ID を示すパラメーターが含まれます。 元の要求で startTime と endTime が指定されていなかった場合、それらは元の要求が出された時点に先行する 24 時間間隔を反映するように設定されます。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761

指定の時間の範囲にある利用可能なすべてのコンテンツのリストを作成するために、NextPageUri ヘッダーがない応答を受信するまで、複数のページを取得することが必要になる場合があります。

通知の受け取り

新しいコンテンツが利用可能になると、サブスクリプションの設定済み Webhook に通知が送信されます。 通知にはテナント ID が含まれるので、同じ Webhook を使用して、サブスクリプションがあるすべてのテナントの通知を受け取ることができます。

通知は、指定の Webhook アドレスに HTTP POST over TLS (TLS 1.0 以降のバージョン) として行われます。 Webhook 構成に認証 ID が含まれている場合、HTTP ヘッダー Webhook-AuthID として送信されます。 HTTP 200 OK 以外の応答はエラーと見なされ、通知が再試行されます。 クライアント証明書ベースの認証を要求するように Webhook を設定することもでき、manage.office.com 証明書を使用して認証されます。

要求の本文には、利用可能なコンテンツ blob を表す、1 つ以上の JSON オブジェクトの配列が含まれます。 通知を比較的小さいサイズにしておくために、各通知内のコンテンツ blob の数は制限されています。 この制限は変更される場合があるので、実装では、固定サイズを前提とするのではなく、配列の長さを照会する必要があります。 各オブジェクトには、/content 操作によって返されたのと同じプロパティ、データが属するテナントの GUID、およびサブスクリプションを作成したアプリケーションの GUID が含まれます。 これにより、Webhook は、複数のテナントとアプリケーションでの使用中に、コンテキストを確立することができます。

• tenantId:コンテンツが属するテナントの GUID です。

• clientId:サブスクリプションを作成したアプリケーションの GUID です。

• contentType:コンテンツ タイプを示します。

• contentId:コンテンツを一意に識別する、符号化文字列です。

• contentUri:コンテンツを取得するときに使用する URL です。

• contentCreated:コンテンツが利用可能になった日付/時刻です。

• contentExpiration:コンテンツ取得の締切となる日付/時刻です。

通知の例を次に示します。

POST https://webhook.myapp.com/o365/ 
Content-Type: application/json; utf-8
Webhook-AuthID: o365activityapinotification

[
    {
        "tenantId": "{GUID}",
        "clientId": "{GUID}",
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z"
    },
    ...
]

通知の失敗および再試行

通知システムは、新しいコンテンツが利用可能になったときに通知を送信します。 通知の送信時に何度も障害が発生した場合は、再試行メカニズムによって再試行の間隔が指数関数的に長くなります。 障害が継続的に発生する場合、Webhook が無効にされ、通知の送信が完全に停止されることがあります。 /start 操作を実行すると、無効にされた Webhook を再度有効にできます。

コンテンツを取得する

コンテンツ blob を取得するには、利用可能なコンテンツのリストと Webhook に送信された通知に含まれている、対応するコンテンツ URI に対して GET 要求を行います。 返されるコンテンツは、JSON 形式の、1 つ以上のアクションまたはイベントのコレクションになります。

要求のサンプル

GET https://manage.office.com/api/v1.0/41463f53-8812-40f4-890f-865bf6e35190/activity/feed/audit/301299007231$301299007231$41463f53881240f4890f865bf6e35190aad2015062920$e1c2ab19858a469fb1f1fd097effffc9$04 HTTP/1.1
Authorization: Bearer eyJ0e...Qa6wg

応答のサンプル

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "CreationTime": "2015-06-29T20:03:19",
        "Id": "80c76bd2-9d81-4c57-a97a-accfc3443dca",
        "Operation": "PasswordLogonInitialAuthUsingPassword",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 9,
        "ResultStatus": "failed",
        "UserKey": "1153977025279851686@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ClientIP": "134.170.188.221",
        "ObjectId": "admin@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "ExtendedProperties": [
            {
                "Name": "LoginError",
                "Value": "-2147217390;PP_E_BAD_PASSWORD;The entered and stored passwords do not match."
            }
        ],
        "Client": "Exchange",
        "LoginStatus": -2147217390,
        "UserDomain": "contoso.onmicrosoft.com"
    },
    {
        "CreationTime": "2015-06-29T20:03:34",
        "Id": "4e655d3f-35fa-42e0-b050-264b2d255c7a",
        "Operation": "PasswordLogonInitialAuthUsingPassword",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 9,
        "ResultStatus": "success",
        "UserKey": "1153977025279851686@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ClientIP": "134.170.188.221",
        "ObjectId": "admin@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "Client": "Exchange",
        "LoginStatus": 0,
        "UserDomain": "contoso.onmicrosoft.com"
    },
    {
        "CreationTime": "2015-06-29T20:04:55",
        "Id": "b567caf0-088e-4c1c-a4ea-633a1e3d66c8",
        "Operation": "Add User.",
        "OrganizationId": "41463f53-8812-40f4-890f-865bf6e35190",
        "RecordType": 8,
        "ResultStatus": "success",
        "UserKey": "1003BFFD8EC47CA6@contoso.onmicrosoft.com",
        "UserType": 0,
        "Workload": "AzureActiveDirectory",
        "ObjectId": "user001@contoso.onmicrosoft.com",
        "UserId": "admin@contoso.onmicrosoft.com",
        "AzureActiveDirectoryEventType": 0,
        "Actor": [
            {
                "ID": "1cef1fdb-ff52-48c4-8e4e-dfb5ea83d357",
                "Type": 2
            },
            {
                "ID": "admin@contoso.onmicrosoft.com",
                "Type": 5
            },
            {
                "ID": "1003BFFD8EC47CA6",
                "Type": 3
            }
        ],
        "ActorContextId": "41463f53-8812-40f4-890f-865bf6e35190",
        "InterSystemsId": "c2ced078-ad57-4079-a743-5c37f5284790",
        "IntraSystemId": "d1497f7e-15b4-49aa-83ad-11a17ca4a2f4",
        "Target": [
            {
                "ID": "user001@contoso.onmicrosoft.com",
                "Type": 5
            },
            {
                "ID": "10037FFE91510806",
                "Type": 3
            }
        ],
        "TargetContextId": "41463f53-8812-40f4-890f-865bf6e35190"
    }
]

通知のリスト作成

この操作では、指定したコンテンツ タイプのすべての通知の試行についてのリストが作成されます。 コンテンツ タイプへのサブスクリプションを開始するときに Webhook を含めなかった場合は、取得される通知はありません。 通知の再試行が障害発生時に行われるため、この操作では同じコンテンツ対する複数の通知が返される場合があり、通知が送信される順序は、コンテンツが利用可能になった順序と必ずしも一致しません (特に障害と再試行が複数回繰り返される場合はそうなります)。

この操作は、Webhook と通知に関連する問題の調査に使用できますが、どのコンテンツが現在取得可能であるかを特定するためには使用しないでください。 その場合は代わりに、/content 操作を実行します。 サブスクリプションの状態が無効である場合は、エラーが返されます。

要求のサンプル

GET {root}/subscriptions/notifications?contentType=Audit.SharePoint&PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg

応答のサンプル

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8

[
    {
        "contentType": "Audit.SharePoint",
        "contentId": "492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentUri": "https://manage.office.com/api/v1.0/f28ab78a-d401-4060-8012-736e373933eb/activity/feed/audit/492638008028$492638008028$f28ab78ad40140608012736e373933ebspo2015043022$4a81a7c326fc4aed89c62e6039ab833b$04",
        "contentCreated": "2015-05-23T17:35:00.000Z",
        "contentExpiration": "2015-05-30T17:35:00.000Z",
        "notificationSent": "2015-05-23T17:36:00.000Z",
        "notificationStatus": "success"

    },
    ...
]

改ページ

ある時間範囲の通知履歴のリストを作成する場合、返される結果の数は、応答のタイムアウトを防ぐために制限されます。 指定の時間範囲内に 1 つの応答で返せるよりもより多くの結果がある場合、結果は切り捨てられ、次ページの結果を取得するために使用する URL を示すヘッダーが応答に追加されます。 URL には、元の要求で指定されたのと同じ startTime パラメーターと endTime パラメーターと、次のページの内部 ID を示すパラメーターが含まれます。 元の要求で startTime と endTime が指定されていなかった場合、それらは元の要求が出された時点に先行する 24 時間間隔を反映するように設定されます。

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
NextPageUri: https://manage.office.com/api/v1/{tenant_id}/activity/feed/subscriptions/content?contentType=Audit.SharePoint&startTime=2015-10-01&endTime=2015-10-02&nextPage=2015101900R022885001761

指定の時間の範囲にある利用可能なすべてのコンテンツのリストを作成するために、NextPageUri ヘッダーがない応答を受信するまで、複数のページを取得することが必要になる場合があります。

リソースのフレンドリ名を取得します。

この操作は、GUID で識別されるデータ フィード内のオブジェクトのフレンドリ名を取得します。 現時点でサポートされているオブジェクトは "DlpSensitiveType" のみです。

要求のサンプル

GET {root}/resources/dlpSensitiveTypes?PublisherIdentifier=46b472a7-c68e-4adf-8ade-3db49497518e
Authorization: Bearer eyJ0e...Qa6wg
Accept-Language: {language code} 

応答のサンプル

HTTP/1.1 200 OK

[
    {
        "id": "50842eb7-edc8-4019-85dd-5a5c1f2bb085",
        "name": "CreditCardNumber"
    }, 
    {
        "id": "0e9b3178-9678-47dd-a509-37222ca96b42",
        "name": "EUDebitCardNumber"
    }, 
    ...
    {
    }
]

API 調整

Office 365 管理アクティビティ API を使用して監査ログにアクセスする組織は、発行者レベルの調整制限により制限されていました。 つまり、発行者が複数のお客様に代わってデータをプルする場合、制限はそれらすべてのお客様で共有されていました。

発行者レベルの制限からテナント レベルの制限に移行しています。 その結果、各組織は、監査データにアクセスするために独自に完全に割り当てられた帯域幅を取得します。 すべての組織には、最初に 1 分あたり 2,000 件の要求のベースラインが割り当てられます。 これは静的な定義済みの制限ではありませんが、組織内のシート数などの要因の組み合わせでモデル化され、Office 365 および Microsoft 365 E5 組織は非 E5 組織の約 2 倍の帯域幅を取得します。 また、サービスの正常性を保護するために、最大帯域幅の上限も設定されます。

詳細については、「Microsoft 365 での高度な監査」の「Office 365 管理アクティビティ API への高帯域幅アクセス」セクションを参照してください。

エラー

サービスでエラーが発生すると、標準の HTTP エラー コード構文を使用して、エラー応答コードが呼び出し元に報告されます。 . 失敗した呼び出しの本文には、1 つの JSON オブジェクトとして追加情報が含まれます。 完全な JSON エラー本文の例を次に示します。

{ 
    "error":{ 
        "code":"AF50000",
        "message": "An internal server error occurred. Retry the request."
    } 
}