設定連接器以匯入實體徽章資料

設定資料連接器以匯入實體徽章資料，例如員工的原始實體存取事件或組織徽章系統產生的任何實體存取警示。實體存取點的範例包括建築物的入口或伺服器機房或資料中心的入口。 Microsoft Purview 測試人員風險管理解決方案會使用實體徽章數據來協助保護您的組織免於組織內的惡意活動或數據竊取。

設定實體徽章連接器包含下列工作：

在 Microsoft Entra ID 中建立應用程式，以存取接受包含實體徽章資料之 JSON 承載的 API 端點。
使用實體徽章資料連接器所定義的結構描述來建立 JSON 承載。
在 Microsoft Purview 入口網站中建立實體徽章資料連接器。
執行指令碼，將實體徽章資料推送至 API 端點。
或者，排程指令碼自動執行，以匯入目前的實體徽章資料。

設定連接器之前

將資料連接器管理員角色指派給在步驟 3 中建立實體徽章連接器的使用者。需要此角色，才能在 Microsoft Purview 入口網站的 [ 資料連接器 ] 頁面上新增連接器。預設情況下，多個角色群組包含此角色。如需這些角色群組的清單，請參閱適用於 Office 365 的 Microsoft Defender 和 Microsoft Purview 合規性中的角色。或者，組織中的管理員可以建立自訂角色群組、指派資料連接器管理員角色，以及將適當的使用者新增為成員。如需詳細指示，請參閱：
- Microsoft Purview 入口網站中的權限
- 適用於 Office 365 的 Microsoft Defender 和 Microsoft Purview 合規性中的角色和角色群組
注意事項

美國政府 GCC High 和 DoD 環境目前不支援資料連接器管理員角色。因此，請將 Exchange Online 中的信箱匯入匯出角色指派給在 GCC High 和 DoD 環境中建立 HR 連接器的使用者。根據預設，Exchange Online 中沒有任何角色群組已指派此角色。您可以在 Exchange Online 中將「信箱匯入匯出」角色新增至「組織管理」角色群組。或者，您可以建立新的角色群組、指派信箱匯入匯出角色，以及將適當的使用者新增為成員。如需詳細資訊，請參閱「在 Exchange Online 中管理角色群組」文章中的建立角色群組或修改角色群組章節。
決定如何每天從組織的實體徽章系統 (擷取或匯出資料，) 並建立 JSON 檔案，如步驟 2 中所述。您在步驟 4 中執行的指令碼會將 JSON 檔案中的資料推送至 API 端點。
瞭解您在步驟 4 中執行的範例腳本會將實體徽章資料從 JSON 檔案推送至連接器 API，讓內部風險管理解決方案可以使用它。任何 Microsoft 標準支援計劃或服務都不支援此範例腳本。它按原樣提供，沒有任何形式的保證。 Microsoft 另外不承擔任何明示或默示的擔保，包括但不限於適售性或適合某特定用途的默示擔保。您承擔因使用或執行範例指令碼和文件而產生的所有風險。在任何情況下，Microsoft、其作者或參與建立、生產或交付指令碼的任何其他人均不對任何損害負責，包括因使用或無法使用範例指令碼或文件而引起的業務利潤損失、業務中斷、業務資訊遺失或其他金錢損失的損害，即使 Microsoft 已被告知此類損害的可能性。
請注意，此連接器可在 Microsoft 365 美國政府雲端的 GCC 環境中使用。第三方應用程式和服務可能涉及在 Microsoft 365 基礎結構外部的第三方系統上儲存、傳輸和處理貴組織的客戶資料。因此，Microsoft Purview 和數據保護承諾不涵蓋這些第三方系統。這不代表將此產品用於連線至協力廠商應用程式的這些協力廠商應用程式符合 FEDRAMP 規範。

步驟 1：在 Microsoft Entra ID 中建立應用程式

首先，在 Microsoft Entra ID 中建立並註冊新的應用程式。應用程式會對應至您在步驟 3 中建立的實體徽章連接器。當您建立應用程式時，Microsoft Entra ID 可以驗證包含實體徽章資料之 JSON 承載的推播要求。在建立此 Microsoft Entra 應用程式期間，請儲存下列資訊。您可以在後續步驟中使用這些值。

Microsoft Entra應用程式 ID 也稱為應用程式 ID 或用戶端 ID ()
Microsoft Entra應用程式密碼也稱為用戶端密碼 ()
租用戶識別碼也稱為 目錄識別碼 ()

如需在 Microsoft Entra ID 中建立應用程式的逐步指示，請參閱向 Microsoft 身分識別平台註冊應用程式。

步驟 2：準備包含實體徽章資料的 JSON 檔案

在此步驟中，您會建立一個 JSON 檔案，其中包含有關員工實體存取資料的資訊。如開始之前一節所述，您需要決定如何從組織的實體徽章系統產生此 JSON 檔案。

注意事項

請勿將非英文字元新增至 JSON 檔案。連接器僅支援英文字元。如果 JSON 包含非英文字元，資料擷取可能會失敗。

JSON 檔案必須符合連接器所需的結構描述定義。下表說明 JSON 檔案所需的結構描述內容：

屬性	描述	資料類型
UserId	員工可以在系統中擁有多個數位身分。輸入必須具有來源系統已解析的 Microsoft Entra 識別碼。	UPN 或電子郵件地址
資產標識符	實體資產或實體存取點的參考 ID。	英數字串
資產名稱	實體資產或實體存取點的易記名稱。	英數字串
事件時間	存取的時間戳記。	日期和時間，UTC 格式
存取狀態	`Success`值或`Failed`	字串

下列範例顯示符合必要結構描述的 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 中執行指令碼時，它會處理您在此步驟中建立的 JSON 檔案，並將其推送至您在步驟 1 中設定的 API 端點。請務必複製建立連接器時產生的 JobId。執行腳本時，您將使用 JobId。

登入 Microsoft Purview 入口網站。
選取設定>資料連接器。
選取 [ 我的連接器]，然後選取 [ 新增連接器]。
從清單中，選擇實體徽章。
在 [驗證認證 ] 頁面上，輸入下列資訊，然後選取 [ 下一步]：
1. 輸入或貼上您在步驟 1 中建立之 Azure 應用程式的 Microsoft Entra 應用程式識別碼。
2. 下載範例結構描述以供參考，以建立JSON檔案。
3. 輸入實體徽章連接器的唯一名稱。
在 [ 檢閱 ] 頁面上，檢閱您的設定，然後選取 [完成] 以建立連接器。
檢視狀態頁面，以確認已建立連接器。此頁面也包含工作 ID。您可以從此頁面或連接器的飛出視窗頁面複製作業識別碼。執行指令碼時，您需要此工作識別碼。

狀態頁面也包含指令碼的連結。請參閱此指令碼，瞭解如何將JSON檔案張貼至API端點。
選取 [完成]。

新的連接器會出現在 連接器 索引標籤的清單中。
選取您剛才建立的實體徽章連接器，以顯示飛出視窗頁面，其中包含連接器的屬性和其他資訊。

步驟 4：執行指令碼以 POST 包含實體徽章資料的 JSON 檔案

若要設定實體徽章連接器，請執行指令碼，將步驟 2) 中建立 (的 JSON 檔案中的實體徽章資料推送至步驟 1) 中建立 (API 端點。我們提供了一個範例腳本供您參考。您可以選擇使用它，或建立自己的指令碼，將 JSON 檔案張貼至 API 端點。

執行腳本之後，包含實體徽章資料的 JSON 檔案會推送至 Microsoft 365 組織，測試人員風險管理解決方案可以存取它。建議您每天發布實體徽章資料。您可以自動執行程序，每天從實體徽章系統產生 JSON 檔案，然後排程指令碼推送資料。

注意事項

API 可以處理最多包含 50,000 筆記錄的 JSON 檔案。

移至此 GitHub 網站以存取範例指令碼。
選取 Raw 按鈕，以文字檢視顯示指令碼。
複製範例指令碼中的所有行，並將它們儲存至文字檔。
如有必要，請修改您組織的範例指令碼。
使用檔案尾碼 .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>"

下表說明要與此指令碼搭配使用的參數及其必要值。針對這些值使用您在先前步驟中取得的資訊。

參數	描述
租戶標識符	這是您在步驟 1 中取得的 Microsoft 365 組織識別碼。您也可以在 Microsoft Entra 系統管理中心的 [概觀] 刀鋒視窗上取得組織的 tenantId。此值可識別您的組織。
appId	這是您在步驟 1 中在 Microsoft Entra ID 中建立之應用程式的 Microsoft Entra 應用程式識別碼。當腳本嘗試存取您的 Microsoft 365 組織時，Microsoft Entra ID 會使用此值進行驗證。
應用程式秘密	這是您在步驟 1 中在 Microsoft Entra ID 中建立之應用程式的 Microsoft Entra 應用程式秘密。 Microsoft Entra ID 也會使用此值進行驗證。
jobId	這是您在步驟 3 中建立之實體徽章連接器的工作識別碼。腳本會使用此值，將推送至 Microsoft 雲端的實體徽章資料與實體徽章連接器產生關聯。
Json檔案路徑	這是本機電腦上的檔案路徑 (您用來執行您在步驟 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 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 開始] 按鈕，然後鍵入 [工作排程器]。
選取 [工作排程器 ] 應用程式以開啟它。
在動作區段中，選取 建立任務。
在 [ 一般 ] 索引標籤上，輸入排程工作的描述性名稱，例如 實體徽章連接器 Script。您也可以新增選用說明。
在 「安全性選項」下，執行下列動作：
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. 選取 [確定] 以儲存新動作的設定。
在 [建立工作 ] 視窗中，選取 [確定] 以儲存排程工作。系統可能會提示您輸入使用者帳戶認證。

新工作會顯示在「工作排程器程式庫」中。

會顯示指令碼上次執行的時間和下次排程執行的時間。您可以雙選任務進行編輯。

您也可以確認腳本上次在合規性中心中對應實體徽章連接器的飛出視窗頁面上執行的時間。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-09-27