访问 Azure Active Directory 报告 API 的先决条件Prerequisites to access the Azure Active Directory reporting API

Azure Active Directory (Azure AD) 报告 API 通过一组基于 REST 的 API,让你以编程方式访问数据。The Azure Active Directory (Azure AD) reporting APIs provide you with programmatic access to the data through a set of REST-based APIs. 可从编程语言和工具中调用这些 API。You can call these APIs from of programming languages and tools.

报告 API 使用 OAuth 授权访问 Web API。The reporting API uses OAuth to authorize access to the web APIs.

若要准备访问报告 API,需要执行以下操作:To prepare your access to the reporting API, you need to:

  1. 分配角色Assign roles
  2. 许可证要求License Requirements
  3. 注册应用程序Register an application
  4. 授予权限Grant permissions
  5. 收集配置设置Gather configuration settings

分配角色Assign roles

若要通过 API 访问报告数据,需分配以下角色之一:To get access to the reporting data through the API, you need to have one of the following roles assigned:

  • 安全读取者Security Reader

  • 安全管理员Security Administrator

  • 全局管理员角色Global Administrator

许可证要求License Requirements

Azure AD 租户只有在关联了 Azure AD Premium 许可证的情况下才能访问租户的登录报告。In order to access the sign-in reports for a tenant, an Azure AD tenant must have associated Azure AD Premium license. 若要访问任何 Azure AD 租户的登录报告,需要 Azure AD Premium P1(或更高版本)许可证。Azure AD Premium P1 (or above) license is required to access sign-in reports for any Azure AD tenant. 或者,如果目录类型为 Azure AD B2C,则无需满足任何其他许可证要求即可通过 API 访问登录报告。Alternatively if the directory type is Azure AD B2C, the sign-in reports are accessible through the API without any additional license requirement.

注册应用程序Register an application

即使是在使用脚本来访问报告 API,也需要注册。Registration is needed even if you're accessing the reporting API using a script. 注册会提供一个 应用程序 ID,该 ID 是进行授权调用所必需的,代码也通过该 ID 来接收令牌。The registration gives you an Application ID, which is required for the authorization calls and enables your code to receive tokens.

若要配置目录以访问 Azure AD 报告 API,必须使用同为 Azure AD 租户中 全局管理员 目录角色成员的 Azure 管理员帐户登录到 Azure 门户To configure your directory to access the Azure AD reporting API, you must sign in to the Azure portal with an Azure administrator account that is also a member of the Global Administrator directory role in your Azure AD tenant.

重要

在具有管理员权限的凭据下运行的应用程序可能具有非常强大的功能,因此请务必将应用程序的 ID 和机密凭据放置在一个安全的位置。Applications running under credentials with administrator privileges can be very powerful, so please be sure to keep the application's ID and secret credentials in a secure location.

若要注册 Azure AD 应用程序,请执行以下操作:To register an Azure AD application:

  1. Azure 门户中,从左侧导航窗格中选择“Azure Active Directory”。 In the Azure portal, select Azure Active Directory from the left navigation pane.

    屏幕截图显示了从 Azure 门户菜单中选择的“Azure Active Directory”。

  2. 在“Azure Active Directory” 页面中,选择“应用注册” 。In the Azure Active Directory page, select App registrations.

    屏幕截图显示了从“管理”菜单中选择的“应用注册”。

  3. 在“应用注册”页面中,选择“新建注册” 。From the App registrations page, select New registration.

    屏幕截图显示了已选定的“新建注册”。

  4. “注册应用程序”页: The Registration an Application page:

    屏幕截图显示了可在其中输入此步骤的值的“注册应用程序”页。

    a.a. 在“名称” 文本框中,键入 Reporting API applicationIn the Name textbox, type Reporting API application.

    b.b. 对于“支持的帐户类型”设置,请选择“仅限此组织中的帐户”。 For Supported accounts type, select Accounts in this organizational only.

    c.c. 在“重定向 URL” 中,选择“Web”文本框 ,然后键入 https://localhostIn the Redirect URL select Web textbox, type https://localhost.

    d.d. 选择“注册” 。Select Register.

授予权限Grant permissions

根据想要访问的 API,你需要向应用授予以下权限:Depending on API you want to access, you need to grant your app the following permissions:

APIAPI 权限Permission
Azure Active DirectoryAzure Active Directory 读取目录数据Read directory data
Microsoft GraphMicrosoft Graph 读取所有审核日志数据Read all audit log data

屏幕截图显示了可在“API 权限”窗格中选择“添加权限”的位置。

以下部分列出适用于这两个 API 的步骤。The following section lists the steps for both APIs. 如果你不想访问其中一个 API,可以跳过相关步骤。If you don't want to access one of the APIs, you can skip the related steps.

若要授予应用程序使用 API 的权限,请执行以下操作:To grant your application permissions to use the APIs:

  1. 选择“API 权限” ,然后选择“添加权限” 。Select API permissions then Add a permission.

    屏幕截图显示了可在其中选择“添加权限”的“API 权限”页。

  2. 在“请求 API 权限”页上, 找到“支持旧版 API” Azure Active Directory GraphOn the Request API permissions page, locate Support legacy API Azure Active Directory Graph.

    屏幕截图显示了可在其中选择“Azure Active Directory Graph”的“请求 API 权限”页。

  3. 在“所需权限”页上选择“应用程序权限”, 展开“目录”复选框 Directory.ReadAllOn the Required permissions page, select Application Permissions, expand Directory checkbox Directory.ReadAll. 选择“添加权限” 。Select Add permissions.

    屏幕截图显示了可在其中选择“应用程序权限”的“请求 API 权限”页。

  4. 在“报表 API 应用程序 - API 权限”页上,选择“授予管理员许可”。 On the Reporting API Application - API Permissions page, select Grant admin consent.

    屏幕截图显示了可在其中选择“授予管理员同意”的“报表 API 应用程序 - API 权限”页。

  5. 注意:Microsoft Graph 在 API 注册过程中默认添加。Note: Microsoft Graph is added by default during API Registration.

    屏幕截图显示了可在其中选择“添加权限”的“API 权限”页。

收集配置设置Gather configuration settings

本部分介绍了如何从目录中获取以下设置:This section shows you how to get the following settings from your directory:

  • 域名Domain name
  • 客户端 IDClient ID
  • 客户端机密Client secret

在配置对报告 API 的调用时需要这些值。You need these values when configuring calls to the reporting API.

获取域名Get your domain name

若要获取域名,请执行以下操作:To get your domain name:

  1. Azure 门户中,在左侧导航窗格中,选择“Azure Active Directory” 。In the Azure portal, on the left navigation pane, select Azure Active Directory.

    屏幕截图显示了从 Azure 门户菜单中选择的“Azure Active Directory”。

  2. 在“Azure Active Directory” 页上,选择“自定义域名” 。On the Azure Active Directory page, select Custom domain names.

    屏幕截图显示了从“Azure Active Directory”中选择的“自定义域名”。

  3. 从域列表中复制域名。Copy your domain name from the list of domains.

获取应用程序的客户端 IDGet your application's client ID

若要获取应用程序的客户端 ID,请执行以下操作:To get your application's client ID:

  1. Azure 门户的左侧导航窗格中,单击“Azure Active Directory” 。In the Azure portal, on the left navigation pane, click Azure Active Directory.

    屏幕截图显示了从 Azure 门户菜单中选择的“Azure Active Directory”。

  2. 从“应用注册” 页面中选择你的应用程序。Select your application from the App Registrations page.

  3. 从应用程序页面中,导航到“应用程序 ID” 并选择“单击以复制”。 From the application page, navigate to Application ID and select Click to copy.

    屏幕截图显示了可以在其中复制应用程序 ID 的“报表 API 应用程序”页。

获取应用程序的客户端机密Get your application's client secret

避免尝试访问审核日志或使用 API 登录时出现的错误。Avoid errors trying to access audit logs or sign-in using the API.

若要获取应用程序的客户端机密,请执行以下操作:To get your application's client secret:

  1. Azure 门户的左侧导航窗格中,单击“Azure Active Directory” 。In the Azure portal, on the left navigation pane, click Azure Active Directory.

    屏幕截图显示了从 Azure 门户菜单中选择的“Azure Active Directory”。

  2. 从“应用注册” 页面中选择你的应用程序。Select your application from the App Registrations page.

  3. 在“API 应用程序”页上选择“证书和机密”,然后在“客户端机密”部分单击“+ 新建客户端机密”。 Select Certificates and Secrets on the API Application page, in the Client Secrets section, click + New Client Secret.

    屏幕截图显示了可以在其中添加客户端密码的“证书和机密”页。

  4. 在“添加客户端机密”页上,添加以下内容: On the Add a client secret page, add:

    a.a. 在“说明” 文本框中,键入 Reporting APIIn the Description textbox, type Reporting API.

    b.b. 选择“2 年内”作为“过期时间”。 As Expires, select In 2 years.

    c.c. 单击“保存” 。Click Save.

    d.d. 复制密钥值。Copy the key value.

排查报告 API 中的错误Troubleshoot errors in the reporting API

本部分列出了使用 Microsoft Graph API 访问活动报告时可能遇到的常见错误消息及其解决步骤。This section lists the common error messages you may run into while accessing activity reports using the Microsoft Graph API and steps for their resolution.

错误:租户不是 B2C,或者租户没有 Premium 许可证Error: Tenant is not B2C or tenant doesn't have premium license

访问登录报告需要 Azure Active Directory Premium 1 (P1) 许可证。Accessing sign-in reports requires an Azure Active Directory premium 1 (P1) license. 如果访问登录时看到此错误消息,请确保你的租户已获得 Azure AD P1 许可证。If you see this error message while accessing sign-ins, make sure that your tenant is licensed with an Azure AD P1 license.

错误:允许的角色中不包括“用户”。Error: The allowed roles does not include User.

避免尝试访问审核日志或使用 API 登录时出现的错误。Avoid errors trying to access audit logs or sign-in using the API. 确保帐户属于 Azure Active Directory 租户中的“安全读取者”或“报表读取者”角色 。Make sure your account is part of the Security Reader or Report Reader role in your Azure Active Directory tenant.

错误:应用程序缺少 AAD“读取目录数据”权限Error: Application missing AAD 'Read directory data' permission

错误:应用程序缺少 Microsoft Graph API“读取所有审核日志数据”权限Error: Application missing Microsoft Graph API 'Read all audit log data' permission

按照访问 Azure Active Directory 报告 API 的先决条件中的步骤操作,确保应用程序使用正确的权限集运行。Follow the steps in the Prerequisites to access the Azure Active Directory reporting API to ensure your application is running with the right set of permissions.

后续步骤Next steps