列出 signIn

  • 项目

命名空间：microsoft.graph

检索租户Microsoft Entra用户登录。 本质上是交互式的登录 (，其中用户名/密码作为身份验证令牌的一部分传递) 并且成功的联合登录当前包含在登录日志中。

最大和默认页面大小为 1,000 个对象，默认情况下，将首先返回最近的登录。 仅可在默认保留期内发生的Microsoft Entra ID登录事件。

注意

本文介绍如何从设备或服务导出个人数据。 这些步骤可用于支持一般数据保护条例 (GDPR) 下的义务。 授权租户管理员可以在Microsoft Entra ID环境中使用 Microsoft Graph 来更正、更新或删除最终用户的身份信息，包括客户和员工用户配置文件或个人数据，例如用户名、工作职务、地址或电话号码。

此 API 可用于以下国家级云部署。

全局服务 美国政府 L4 美国政府 L5 (DOD) 由世纪互联运营的中国
✅ ❌ ❌ ❌

权限

要调用此 API，需要以下权限之一。 若要了解详细信息，包括如何选择权限的信息，请参阅权限。

权限类型 权限（从最低特权到最高特权）
委派（工作或学校帐户） AuditLog.Read.All 和 Directory.Read.All
委派（个人 Microsoft 帐户） 不支持
Application AuditLog.Read.All 和 Directory.Read.All

应用必须正确注册到Microsoft Entra ID。

除了委派的权限外，已登录用户还需要至少属于以下Microsoft Entra角色之一：

  • 全局读取者
  • 报告读取者
  • 安全管理员
  • 安全操作员
  • 安全信息读取者

在登录中查看应用的条件访问 (CA) 策略

appliedConditionalAccessPolicies 属性中列出的应用 CA 策略仅适用于具有允许他们读取条件访问数据的角色的用户和应用。 如果用户或应用有权读取登录日志，但无权读取条件访问数据，则将省略响应中的 appliedConditionalAccessPolicies 属性。 以下Microsoft Entra角色授予用户查看条件访问数据的权限：

  • 全局读取者
  • 安全管理员
  • 安全信息读取者
  • 条件访问管理

应用程序必须至少具有以下权限之一才能在登录日志中查看 appliedConditionalAccessPolicy 对象：

  • Policy.Read.All
  • Policy.ReadWrite.ConditionalAccess
  • Policy.Read.ConditionalAccess

注意：Microsoft Entra具有任何权限的用户都可以读取其用户是执行组件登录的登录日志。 此功能可帮助用户发现其帐户中的意外活动。 用户无法从自己的日志中读取 CA 数据，除非他们具有上面标识的 CA 权限之一。

HTTP 请求

GET /auditLogs/signIns

可选的查询参数

此方法支持 $top、 $skiptoken和 $filter OData 查询参数，以帮助自定义响应。 若要了解一般信息，请参阅 OData 查询参数。

若要避免请求超时，请使用获取所有登录的时间范围应用 $filter 参数，如 示例 1 中所示。

请求标头

名称 说明
Authorization 持有者 {token}。 必填。 详细了解 身份验证和授权。

响应

如果成功，此方法在响应正文中返回 200 OK 响应代码和 signIn 对象集合。 对象的集合根据 createdDateTime 按降序列出。

示例

示例 1：列出特定时间段内的所有登录

请求

以下示例演示了列出特定时间段内所有登录的请求。

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?$filter=createdDateTime ge 2024-07-01T00:00:00Z and createdDateTime le 2024-07-14T23:59:59Z

响应

以下示例显示了相应的响应。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signIns?$top=1&$skiptoken=9177f2e3532fcd4c4d225f68f7b9bdf7_1",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:35Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}

示例 2：检索以“Graph”开头的 appDisplayName 的前 10 个登录应用

请求

以下示例显示了一个请求。

GET https://graph.microsoft.com/v1.0/auditLogs/signIns?&$filter=startsWith(appDisplayName,'Graph')&$top=10

响应

以下示例显示了相应的响应。 响应包含一个 @odata.nextLink 属性，该属性包含可用于检索接下来 10 个结果的 URL。

注意：为了提高可读性，可能缩短了此处显示的响应对象。

HTTP/1.1 200 OK
Content-type: application/json

{
    "@odata.context": "https://graph.microsoft.com/v1.0/$metadata#auditLogs/signIns",
    "@odata.nextLink": "https://graph.microsoft.com/v1.0/auditLogs/signins?$filter=startsWith(appDisplayName%2c%27Graph%27)&$top=10&$skiptoken=70f66c0893886b49370ffdb44cd8d137b1a12b9ba02f34a16f33c5e0f7c42fc7",
    "value": [
        {
            "id": "66ea54eb-6301-4ee5-be62-ff5a759b0100",
            "createdDateTime": "2023-12-01T16:03:32Z",
            "userDisplayName": "Test Contoso",
            "userPrincipalName": "testaccount1@contoso.com",
            "userId": "26be570a-ae82-4189-b4e2-a37c6808512d",
            "appId": "de8bc8b5-d9f9-48b1-a8ad-b748da725064",
            "appDisplayName": "Graph explorer",
            "ipAddress": "131.107.159.37",
            "clientAppUsed": "Browser",
            "correlationId": "d79f5bee-5860-4832-928f-3133e22ae912",
            "conditionalAccessStatus": "notApplied",
            "isInteractive": true,
            "riskDetail": "none",
            "riskLevelAggregated": "none",
            "riskLevelDuringSignIn": "none",
            "riskState": "none",
            "riskEventTypes": [],
            "resourceDisplayName": "Microsoft Graph",
            "resourceId": "00000003-0000-0000-c000-000000000000",
            "status": {
                "errorCode": 0,
                "failureReason": null,
                "additionalDetails": null
            },
            "deviceDetail": {
                "deviceId": "",
                "displayName": null,
                "operatingSystem": "Windows 10",
                "browser": "Edge 80.0.361",
                "isCompliant": null,
                "isManaged": null,
                "trustType": null
            },
            "location": {
                "city": "Redmond",
                "state": "Washington",
                "countryOrRegion": "US",
                "geoCoordinates": {
                    "altitude": null,
                    "latitude": 47.68050003051758,
                    "longitude": -122.12094116210938
                }
            },
            "appliedConditionalAccessPolicies": [
                {
                    "id": "de7e60eb-ed89-4d73-8205-2227def6b7c9",
                    "displayName": "SharePoint limited access for guest workers",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
                {
                    "id": "6701123a-b4c6-48af-8565-565c8bf7cabc",
                    "displayName": "Medium signin risk block",
                    "enforcedGrantControls": [],
                    "enforcedSessionControls": [],
                    "result": "notEnabled"
                },
              ]
        }
    ]
}