设置连接器以导入物理坏点数据

项目
05/01/2024

可以设置数据连接器来导入物理坏点数据，例如员工的原始物理访问事件或组织坏点系统生成的任何物理访问警报。物理接入点的示例包括建筑物的入口或服务器机房或数据中心的入口。 Microsoft Purview 预览体验成员风险管理解决方案可以使用物理恶意数据，以帮助保护组织免受组织内部的恶意活动或数据盗窃的影响。

设置物理坏点连接器包括以下任务：

在 Microsoft Entra ID 中创建应用，以访问接受包含物理坏点数据的 JSON 有效负载的 API 终结点。
使用物理坏点数据连接器定义的架构创建 JSON 有效负载。
在 Microsoft Purview 门户或Microsoft Purview 合规门户中创建物理坏点数据连接器。
运行脚本，将物理坏点数据推送到 API 终结点。
（可选）将脚本计划为自动运行以导入当前物理的坏点数据。

提示

如果你不是 E5 客户，请使用 90 天Microsoft Purview 解决方案试用版来探索其他 Purview 功能如何帮助组织管理数据安全性和合规性需求。立即在 Microsoft Purview 试用中心开始。了解有关注册和试用条款的详细信息。

设置连接器之前

必须在步骤 3 中创建物理标记连接器的用户分配数据连接器管理员角色。需要此角色才能在 Microsoft Purview 门户或合规性门户的 “数据连接器 ”页上添加连接器。默认情况下，此角色将添加到多个角色组。有关这些角色组的列表，请参阅 Microsoft Defender for Office 365 中的角色和 Microsoft Purview 合规性。或者，组织中的管理员可以创建自定义角色组，分配数据连接器管理员角色，然后将相应的用户添加为成员。有关说明，请参阅以下内容：
注意

美国政府 GCC High 和 DoD 环境中当前不支持数据连接器管理员角色。因此，必须在 Exchange Online 中为在 GCC High 和 DoD 环境中创建 HR 连接器的用户分配邮箱导入导出角色。默认情况下，不会向 Exchange Online 中任何角色组分配此角色。可以将邮箱导入导出角色添加到 Exchange Online 中的组织管理角色组。或者，可以创建新的角色组，分配“邮箱导入导出”角色，然后将相应的用户添加为成员。有关详细信息，请参阅“在 Exchange Online 中管理角色组”一文中的创建角色组或修改角色组部分。
需要确定如何每天) 从组织的物理切分系统 (检索或导出数据，并创建步骤 2 中所述的 JSON 文件。在步骤 4 中运行的脚本会将 JSON 文件中的数据推送到 API 终结点。
步骤 4 中运行的示例脚本将物理坏点数据从 JSON 文件推送到连接器 API，以便内部风险管理解决方案可以使用这些数据。任何Microsoft标准支持计划或服务都不支持此示例脚本。示例脚本“原样”提供，不提供任何形式的保证。 Microsoft 进一步拒绝所有默示保证，包括但不限于针对特定用途的适销性或适用性的任何默示保证。由于示例脚本及文档的使用或性能所引起的全部风险均由你承担。在任何情况下，对于由于使用或者无法使用示例脚本或文档所引起的任何损失（包括但不限于商业利润损失、业务中断、商业信息丢失或者其他经济损失），Microsoft、其作者或者参与创建、制作或交付脚本的任何人概不负责，即使 Microsoft 已被告知可能会出现此类损失。
此连接器在 Microsoft 365 美国政府云中的 GCC 环境中可用。第三方应用程序和服务可能涉及在 Microsoft 365 基础结构之外的第三方系统上存储、传输和处理组织的客户数据，因此，Microsoft Purview 和数据保护承诺未涵盖这些数据。 Microsoft不表示使用此产品连接到第三方应用程序意味着这些第三方应用程序符合 FEDRAMP。

步骤 1：在 Microsoft Entra ID 中创建应用

第一步是在 Microsoft Entra ID 中创建和注册新应用。该应用将对应于在步骤 3 中创建的物理坏点连接器。创建此应用将允许Microsoft Entra ID对包含物理坏点数据的 JSON 有效负载的推送请求进行身份验证。创建此Microsoft Entra应用期间，请务必保存以下信息。这些值将在后续步骤中使用。

Microsoft Entra应用程序 ID (也称为应用 ID 或客户端 ID)
Microsoft Entra应用程序机密 (也称为客户端机密)
租户 ID (也称为 目录 ID)

有关在 Microsoft Entra ID 中创建应用的分步说明，请参阅向Microsoft 标识平台注册应用程序。

步骤 2：准备包含物理坏点数据的 JSON 文件

下一步是创建一个 JSON 文件，其中包含有关员工物理访问数据的信息。如开始前部分所述，需要确定如何从组织的物理坏处系统生成此 JSON 文件。

注意

不要向 JSON 文件添加非英语字符。连接器仅支持英文字符;如果 JSON 包含非英语字符，则数据引入可能会失败。

JSON 文件必须符合连接器所需的架构定义。下面是 JSON 文件所需的架构属性的说明：

属性	说明	数据类型
UserID	员工可以跨系统拥有多个数字标识。输入需要具有源系统已解析Microsoft Entra ID。	UPN 或电子邮件地址
AssetId	物理资产或物理接入点的引用 ID。	字母数字字符串
AssetName	物理资产或物理接入点的友好名称。	字母数字字符串
EventTime	访问的时间戳。	日期和时间，采用 UTC 格式
AccessStatus	`Success`或的值`Failed`	String

下面是符合所需架构的 JSON 文件示例：

[
    {
        "UserId":"sarad@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T01:57:49",
        "AccessStatus":"Failed"
    },
    {
        "UserId":"pilarp@contoso.com",
        "AssetId":"Mid-Sec-7",
        "AssetName":"Main Building 1st Floor Mid Section",
        "EventTime":"2019-07-04T02:57:49",
        "AccessStatus":"Success"
    }
]

在步骤 3 中创建物理坏点连接器时，还可以从工作流下载 JSON 文件的以下架构定义。

{
   "title" : "Physical Badging Signals",
   "description" : "Access signals from physical badging systems",
   "DataType" : {
      "description" : "Identify what is the data type for input signal",
      "type" : "string",
   },
   "type" : "object",
   "properties": {
      "UserId" : {
         "description" : "Unique identifier AAD Id resolved by the source system",
         "type" : "string",
      },
      "AssetId": {
         "description" : "Unique ID of the physical asset/access point",
         "type" : "string",
      },
      "AssetName": {
         "description" : "friendly name of the physical asset/access point",
         "type" : "string",
      },
      "EventTime" : {
         "description" : "timestamp of access",
         "type" : "string",
      },
      "AccessStatus" : {
         "description" : "what was the status of access attempt - Success/Failed",
         "type" : "string",
      },
   }
   "required" : ["UserId", "AssetId", "EventTime" "AccessStatus"]
}

步骤 3：创建物理坏点连接器

下一步是在 Microsoft Purview 门户或合规性门户中创建物理标记连接器。在步骤 4 中运行脚本后，在步骤 3 中创建的 JSON 文件将被处理并推送到步骤 1 中配置的 API 终结点。在此步骤中，请务必复制创建连接器时生成的 JobId。运行脚本时，将使用 JobId。

为正在使用的门户选择相应的选项卡。根据 Microsoft 365 计划，Microsoft Purview 合规门户已停用或即将停用。

若要详细了解 Microsoft Purview 门户，请参阅 Microsoft Purview 门户。若要了解有关合规性门户的详细信息，请参阅 Microsoft Purview 合规门户。

Microsoft Purview 门户
合规性门户

登录到 Microsoft Purview 门户。
选择 “设置”>“数据连接器”。
选择 “我的连接器”，然后选择“ 添加连接器”。
从列表中，选择 “物理坏点”。
在 “身份验证凭据 ”页上，执行以下操作，然后选择“ 下一步”：
1. 键入或粘贴在步骤 1 中创建的 Azure 应用的Microsoft Entra应用程序 ID。
2. 下载示例架构以供参考，以创建 JSON 文件。
3. 为物理标记连接器键入唯一名称。
在“ 审阅 ”页上，查看设置，然后选择“ 完成 ”以创建连接器。
将显示一个状态页，确认已创建连接器。此页还包含作业 ID。可以从此页或连接器的浮出控件页复制作业 ID。运行脚本时需要此作业 ID。

状态页还包含指向脚本的链接。请参阅此脚本，了解如何将 JSON 文件发布到 API 终结点。
选择“完成”。

新连接器显示在“ 连接器 ”选项卡上的列表中。
选择刚刚创建的物理标记连接器以显示浮出控件页，其中包含有关连接器的属性和其他信息。

步骤 4：运行脚本以 POST 包含物理坏点数据的 JSON 文件

设置物理标记连接器的下一步是运行一个脚本，该脚本会将在步骤 2) 中创建的 JSON 文件 (的物理坏点数据推送到步骤 1 中创建的 API 终结点。我们提供了一个示例脚本供参考，你可以选择使用它或创建自己的脚本来将 JSON 文件发布到 API 终结点。

运行脚本后，包含物理坏处数据的 JSON 文件将推送到 Microsoft 365 组织，内部风险管理解决方案可在其中对其进行访问。建议每天发布物理坏点数据。为此，可以自动执行每天从物理坏点系统生成 JSON 文件的过程，然后计划脚本来推送数据。

注意

API 可以处理的 JSON 文件中的最大记录数为 50,000 条记录。

转到此 GitHub 站点以访问示例脚本。
选择“ 原始 ”按钮，在文本视图中显示脚本
复制示例脚本中的所有行，然后将其保存到文本文件中。
如有必要，请修改组织的示例脚本。
使用 .ps1 的文件名后缀将文本文件另存为Windows PowerShell脚本文件;例如，PhysicalBadging.ps1。
在本地计算机上打开命令提示符，并转到保存脚本的目录。

运行以下命令，将 JSON 文件中的物理坏点数据推送到 Microsoft 云：例如：

.\PhysicalBadging.ps1 -tenantId "<Tenant Id>" -appId "<Azure AD App Id>" -appSecret "<Azure AD App Secret>" -jobId "Job Id" -jsonFilePath "<records file path>"

下表介绍了要用于此脚本的参数及其所需值。在前面的步骤中获取的信息将用于这些参数的值中。

参数	说明
tenantId	这是在步骤 1 中获取的 Microsoft 365 组织的 ID。还可以在Microsoft Entra 管理中心的“概述”边栏选项卡上获取组织的 tenantId。这用于标识组织。
appId	这是在步骤 1 Microsoft Entra ID 中创建的应用Microsoft Entra应用程序 ID。当脚本尝试访问 Microsoft 365 组织时，Microsoft Entra ID使用此脚本进行身份验证。
appSecret	这是在步骤 1 Microsoft Entra ID 中创建的应用Microsoft Entra应用程序机密。这还用于身份验证。
jobId	这是在步骤 3 中创建的物理坏点连接器的作业 ID。这用于将推送到 Microsoft 云的物理坏点数据与物理坏点连接器相关联。
JsonFilePath	这是本地计算机上的文件路径， (用于运行在步骤 2 中创建的 JSON 文件的脚本) 路径。此文件必须遵循步骤 3 中所述的示例架构。

下面是使用每个参数的实际值的物理标记连接器脚本的语法示例：

.\PhysicalBadging.ps1 -tenantId d5723623-11cf-4e2e-b5a5-01d1506273g9 -appId 29ee526e-f9a7-4e98-a682-67f41bfd643e -appSecret MNubVGbcQDkGCnn -jobId b8be4a7d-e338-43eb-a69e-c513cd458eba -jsonFilePath 'C:\Users\contosoadmin\Desktop\Data\physical_badging_data.json'

如果上传成功，脚本将显示 “上传成功” 消息。

如果有多个 JSON 文件，则必须为每个文件运行脚本。

步骤 5：监视物理坏点连接器

创建物理标记连接器并推送物理坏点数据后，可以在 Microsoft Purview 门户或合规性门户中查看连接器和上传状态。如果将脚本计划为定期自动运行，还可以在上次运行脚本后查看当前状态。

为正在使用的门户选择相应的选项卡。根据 Microsoft 365 计划，Microsoft Purview 合规门户已停用或即将停用。

若要详细了解 Microsoft Purview 门户，请参阅 Microsoft Purview 门户。若要了解有关合规性门户的详细信息，请参阅 Microsoft Purview 合规门户。

Microsoft Purview 门户
合规性门户

登录到 Microsoft Purview 门户。
选择 “设置”>“数据连接器”。
选择“ 我的连接器”，然后选择创建的用于显示浮出控件页的物理标记连接器。此页包含有关连接器的属性和信息。
在“ 上次导入”下，选择“ 下载日志 ”链接以打开 (或保存) 连接器的状态日志。此日志包含有关每次运行脚本并将 JSON 文件中的数据上传到Microsoft云的信息。

RecordsSaved 字段指示 JSON 文件中已上传的记录数。例如，如果 JSON 文件包含四条记录，则如果脚本成功上传 JSON 文件中的所有记录， 则 RecordsSaved 字段的值为 4。 RecordsSkipped 字段指示 JSON 文件中跳过的记录数。在 JSON 文件中上传记录之前，会验证记录的Email ID。跳过具有无效Email ID 的任何记录，并且相应的Email ID 显示在“EmailIdsNotSaved”字段中

如果尚未在步骤 4 中运行脚本，则会在 “上次导入”下显示用于下载脚本的链接。可以下载该脚本，然后按照步骤 4 中的步骤运行该脚本。

(可选) 步骤 6：计划脚本以自动运行

若要确保组织的最新物理错误数据可用于内部风险管理解决方案等工具，建议将脚本计划为定期自动运行，例如每天运行一次。如果不是相同的) 计划，这还要求将物理坏点数据更新为类似 (上的 JSON 文件，以便包含有关离开组织的员工的最新信息。目标是上传最新的物理记号数据，以便物理坏点连接器可用于内部风险管理解决方案。

可以使用 Windows 中的任务计划程序应用每天自动运行脚本。

在本地计算机上，选择“Windows 开始” 按钮，然后键入 “任务计划程序”。
选择 “任务计划程序” 应用将其打开。
在 “操作” 部分中，选择“ 创建任务”。
在“ 常规 ”选项卡上，键入计划任务的描述性名称;例如 ，物理标记连接器脚本。还可以添加可选说明。
在 “安全选项”下，执行以下操作：
1. 确定是仅在登录到计算机时运行脚本，还是在登录与否时运行脚本。
2. 确保选中“ 使用最高权限运行 ”复选框。
选择“ 触发器 ”选项卡，选择“ 新建”，然后执行以下操作：
1. 在 “设置”下，选择“ 每日 ”选项，然后选择首次运行脚本的日期和时间。该脚本将每天在同一指定时间运行。
2. 在 “高级设置”下，确保选中“ 已启用 ”复选框。
3. 选择“确定”。
选择“ 操作 ”选项卡，选择“ 新建”，然后执行以下操作：
1. 在 “操作” 下拉列表中，确保已选择 “启动程序 ”。
2. 在“ 程序/脚本 ”框中，选择“ 浏览”，转到以下位置并选择它，以便在框中显示路径：C:\Windows\System32\WindowsPowerShell\v1.0\powershell.exe。
3. 在 “添加参数 (可选) ”框中，粘贴在步骤 4 中运行的相同脚本命令。例如， .\PhysicalBadging.ps1-tenantId“d5723623-11cf-4e2e-b5a5-01d1506273g9” -appId “c12823b7-b55a-4989-faba-02de41bb97c3 ” -appSecret “MNubVGbcQDkGCnn” -jobId “e081f4f4-3831-48d6-7bb3-fcfab1581458” -jsonFilePath “C：\Users\contosoadmin\Desktop\Data\physical_badging_data.json”
4. 在“ (可选) ”框中，粘贴步骤 4 中运行的脚本的文件夹位置。例如，C：\Users\contosoadmin\Desktop\Scripts。
5. 选择 “确定” 以保存新操作的设置。
在 “创建任务” 窗口中，选择“ 确定” 以保存计划的任务。系统可能会提示输入用户帐户凭据。

新任务显示在任务计划程序库中。

显示上次运行脚本的时间和下次计划运行的时间。可以双击任务进行编辑。

还可以验证脚本上次在合规中心相应物理标记连接器的浮出控件页上运行的时间。

通过