使用 API 導向匯入匯入組織資料 (首次匯入) (預覽)

重要事項

此功能僅限公開預覽用戶使用。預覽功能可能尚未完整，且在更廣泛版本中推出前可能會有變動。此預覽功能允許個人資料處理。欲了解更多資訊，請參閱 Microsoft 產品與服務資料保護附錄中的「預覽」部分。

您的組織資料可以透過三種方式出現在 Viva Insights 網頁應用程式中：透過預設來源 Microsoft Entra ID;或您作為 Insights 管理員直接上傳至 Viva Insights 的個別 .csv 檔案;或是您、您的來源系統管理員與 Microsoft 365 IT 管理員設定的基於 API 的資料匯入。

本文談到第三種選項，匯入資料。

匯入時，你將資料來源系統的資料透過壓縮檔帶到 Viva Insights 人力資源資料輸入 API。您可以：

建立一個自訂應用程式，將資料從來源系統匯出成壓縮檔。接著，使用同一個應用程式，利用下方的 API 資訊匯入該資料。
建立一個自訂應用程式，將資料從來源系統匯出成壓縮檔。接著，執行我們開發的 C# 控制台應用程式，將資料匯入 Viva Insights。
建立一個自訂應用程式，將資料從來源系統匯出成壓縮檔。接著，執行我們自己寫的 PowerShell 腳本，把資料匯入 Viva Insights。
使用我們的 Azure Data Factory (ADF) 模板將資料傳送到基於 API 的匯入。

不過，在你執行應用程式並開始將資料轉移到 Viva Insights 之前，你需要協調 Microsoft 365 管理員與 Insights 管理員 (Insights 管理) 之間的一些任務。請參閱工作流程以了解所需步驟的概述。

重要事項

只有在第一次匯入組織資料時，才使用以下步驟。如果這不是你第一次匯入，請參考「匯入組織資料 (後續匯入) 以刷新先前匯入的資料。

工作流程

設定:
1. 資料來源管理員會產生安全憑證並提供給 Microsoft 365 管理員。
2. 利用安全憑證，Microsoft 365 管理員會在 Azure 註冊一個新應用程式。
3. Insights 管理員會利用應用程式註冊時的 ID，設定匯入。
4. 資料來源管理員負責準備資料，並負責以下其中之一：
  1. 他們會用基於我們 API 的自訂應用程式從他們的來源系統匯出資料，然後用同一個應用程式匯入資料到 Viva Insights。
  2. 他們會用基於我們 API 的自訂應用程式從他們的來源系統匯出資料，然後用我們的 C# 解決方案或 PowerShell 腳本，再匯入資料到 Viva Insights。
驗證：Viva Insights 驗證您的資料。 (如果驗證失敗，你可以從「驗證失敗」中描述的幾個選項中選擇 )
處理：Viva Insights 處理您的資料。 (如果處理失敗，你可以從「處理失敗」中描述的幾個選項中選擇 )

資料成功驗證並處理後，整體資料匯入任務完成。

安裝程式

產生安全憑證

適用於：資料來源管理員

要開始將來源檔案的資料匯入 Viva Insights，Microsoft 365 管理員需要在 Azure 建立並註冊應用程式。作為資料來源管理員，你需要協助 Microsoft 365 管理員註冊他們的應用程式，並提供安全憑證。

以下是該做的事：

請依照本文指示建立憑證：建立自簽公開憑證以驗證您的申請
將產生的憑證寄給 Microsoft 365 管理員。

暫時就這樣。如果你想提前開始下一步，請依照「匯出資料的設定頻率」步驟操作。

Register a new app in Azure

適用於：Microsoft 365 管理員

注意事項

欲了解更多關於在 Azure 註冊應用程式的資訊，請參閱快速入門：使用 Microsoft 身分識別平台註冊應用程式。

從 Microsoft 管理中心左側的欄選「 所有管理中心」。這個選項會出現在清單的最後一個。
選擇 Microsoft Entra ID。
建立新的應用程式註冊：
1. 在上方工具列，選擇 「新增 > 應用程式註冊」。
2. 在結果畫面上：
  1. 給你的應用程式取個名字。
  2. 在 支援帳號類型中，保留第一個選項，僅此 組織目錄中的帳號 ([您的組織] - 單一租戶) ，選擇。
  3. 請選擇螢幕底部的 「登記 」按鈕。
3. 回到概覽畫面後，複製 應用程式 (客戶) ID 和 目錄 (租戶) ID。
  
  重要事項
  
  把這些身分證放在手邊。你之後還需要提供。
新增證書：
1. 選擇新增憑證或秘密。
2. 選擇 上傳憑證。
3. 上傳資料來源管理員給你的憑證，並新增說明。 選取 [新增] 按鈕。
移除 API 權限：
1. 從左邊欄選擇 API 權限 。
2. 對於每個列出 的 API / 權限 名稱，選擇 API 右側的省略號 (......) ——例如， Microsoft Graph。
3. 選擇 移除權限。
4. 確認移除。
當你移除這些項目的權限時，就是確保應用程式只擁有它需要的權限。
分享你在步驟3c中記下的ID：
1. 把應用程式 ID 給 Insights 管理員。
2. 給資料來源管理員應用程式 ID 和租戶 ID。

在 Viva Insights 中設定匯入

適用於：Insights 管理員

匯入可從兩個地方之一開始： 資料樞紐 頁面或組織資料頁面，資料連結下。
1. 資料來源：Data hub：
  1. 在 資料來源 區塊，找到 基於 API 的匯入 選項。選取 [開始] 按鈕。
2. 資料來源：Data 連線：
  1. 在 「目前來源」旁邊，選擇 「資料來源 」按鈕。
  2. 會出現 一個切換至：基於 API 的匯入 視窗。選取 [開始]。
在 基於 API 的組織資料匯入 頁面上：
1. 給你的連結取個名字。
2. 輸入你的 Microsoft 365 管理員給你的應用程式 ID。
3. 儲存。
選擇你在步驟 3a 中命名的連線作為新的資料來源。
聯絡資料來源管理員，請他們將組織資料傳送到 Viva Insights。

準備、匯出及匯入組織資料

準備資料的技巧

對於新資料，請包含所有員工的完整歷史資料。
匯入公司所有員工的組織資料，包括持照與非持牌員工。
請參閱範例 .csv 範本，了解資料結構與指引，以避免常見問題，如獨特值過多或過少、欄位重複、資料格式無效等。

匯出資料時設定頻率

你決定的頻率是每月一次、每週一次等 () 讓你的自訂應用程式從來源系統匯出組織資料，匯出成壓縮檔並存到檔案中。這個壓縮夾是基於這裡的。你的壓縮檔需要包含一個 data.csv 檔案和一個metadata.json檔案。

以下是關於這些檔案及其所需內容的更多細節：

data.csv

把你想匯入的所有欄位都加入這個檔案。請務必依照我們在「準備組織資料」中的指引格式化。

metadata.json

請說明你正在執行的刷新類型，以及 Viva Insights 應該如何映射你的欄位：

"DatasetType": "HR" (第二行) 。就這樣吧。
"IsBootstrap": (第三行) 。用來 "true" 表示完整刷新，並 "false" 表示增量刷新。
"ColumnMap":. 如果你使用與 Viva Insights 不同的名稱，請將每個欄位標頭名稱改成與你來源系統中使用的名稱一致。

重要事項

移除 .csv 檔案中不存在的欄位。

映射範例

以下範例代表metadata.json檔案中的一個欄位：

"PersonId": {
    "name": "PersonId",
    "type": "EmailType"

"PersonId": { 對應來源欄位名稱。
“name” : “PersonId”, 對應 Viva Insights 的欄位名稱。
"type": "EmailType" 對應欄位的資料型態。

假設你的來源系統用這個 PersonId欄位標頭代替 Employee 。為了確保欄位正確對應，請編輯下方第一行，使其看起來像這樣：

      "Employee": {
        "name": "PersonId",
        "type": "EmailType"

當你上傳資料後，你的 Employee 領域就會變成 PersonId Viva Insights。

匯入你的資料

要將資料匯入 Viva Insights，您可以從四個選項中選擇：

使用我們的 API 建立一個自訂應用程式，能依照你選擇的頻率匯出和匯入資料。深入了解。
在你的主機上執行我們的 C# 解決方案，該方案是基於我們的 API。深入了解。
執行我們的 PowerShell 腳本，這腳本同樣是基於我們的 API。深入了解。
使用我們的 Azure Data Factory (ADF) 模板將資料傳送到基於 API 的匯入。深入了解。

注意事項

我們的 C# 和 PowerShell 解決方案只會匯入資料到 Viva Insights。他們不會從你的來源系統匯出資料。

在使用以下任何選項之前，請確保你已掌握以下資訊：

應用程式 (客戶) ID。在Azure 入口網站註冊應用程式的應用程式資訊中，客戶) ID (應用程式中找到此 ID。
用戶端秘密：這是應用程式在請求標記時用來證明身份的秘密字串。它也被稱為應用程式密碼。這個祕密只有在建立客戶端祕密時才首次顯示。要建立新的客戶端秘密，請參見入口網站中的「建立 Microsoft Entra 應用程式與服務主體」。
證書名稱。這個名稱是在你註冊的應用程式中設定的。上傳憑證後，憑證名稱會顯示在 Azure 入口網站的描述中。你可以用憑證名稱作為用戶端秘密的替代方案。
zip 檔和 zip 檔的路徑。不要更改檔名 data.csv 和 metadata.json。
Microsoft Entra tenant ID. 也可以在應用程式的總覽頁面「 租戶) ID 目錄」中找到 (此 ID。
比例單位：例如，為租戶提供的單位。 novaprdwus2-01

關於 Viva Insights 人力資源資料輸入 API

請參考以下指令：

[請求標頭]

這兩個請求標頭是所有以下提及 API 所必需的

x-nova-scaleunit: <ScaleUnit obtained from Insights setup connection page>

Authentication: Bearer <Oauth token from AAD>

注意事項

Generate Active Directory OAuth token for registered app (daemon app auth flow) use：
Authority: https://login.microsoftonline.com

Tenant: <target AAD tenant ID>

Audience: https://api.orginsights.viva.office.com

欲了解更多關於產生權杖的資訊，請參見：使用 Microsoft 認證函式庫取得並快取 (MSAL)

取得連接器/ping來檢查該連接器是否已設定為租戶

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR

[回應主體]

若連接器已設定，並授權呼叫者應用程式 (ID) ：

200:  

{ 
       “ConnectorId”: “Connector-id-guid” 

}

如果洞察管理員已經移除連接器，或該連接器尚未由洞察管理員設定：

403: Forbidden.

推送資料

1P/3P 問卷調查應用程式呼叫 Viva Insights API 來推送內容

[POST] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/HR/ingestions/fileIngestion

[Body] 檔案內容為多部分/表單資料

類型：壓縮壓縮檔

待存檔內容：

Metadata.json

Data.csv

[請求身體]

Body: 

{ 

   "$content-type": "multipart/form-data", 

   "$multipart":  

    [ 

        { 

            "headers":  

                { 

                    "Content-Disposition": "form-data; name=\"file\"; filename=info" 

                   }, 

            "body": @{body('Get_blob_content_(V2)')} 

         } 

    ] 

}

[回應正文]

200:  
{ 

  "FriendlyName": "Data ingress", 

  "Id": "<ingestion Id>", 

  "ConnectorId": "<connector Id>", 

  "Submitter": "System", 

  "StartDate": "2023-05-08T19:07:07.4994043Z", 

  "Status": "NotStarted", 

  "ErrorDetail": null, 

  "EndDate": null, 

  "Type": "FileIngestion" 

}

若連接器未設定：

403: Forbidden

如果連接器已設定但先前的擷取尚未完成：

400: Bad request: Previous ingestion is not complete.

投票狀態

API 用於輪詢擷取狀態，因為資料擷取是長期執行的操作。

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>/ingress/connectors/Hr/ingestions/fileIngestion/{ingestionId:guid}

[回應]

200: 
{ 

            "FriendlyName": "Data ingress", 

            "Id": "<ingestion Id>", 

            "ConnectorId": "<connector Id>", 

            "Submitter": "System", 

            "StartDate": "2023-05-08T19:05:44.2171692Z", 

            		  "Status": "NotStarted/ExtractionComplete/ValidationFailed 

/Completed/", 

            "ErrorDetail": null, 

            "EndDate": "2023-05-08T20:09:18.7301504Z", 

            "Type": "FileIngestion" 

},

如果驗證失敗 (資料) 問題，下載錯誤串流

[GET] https://api.orginsights.viva.office.com/v1.0/scopes/<tenantId>//Hr/ingestions/{ingestionId}/errors

[回應]

200: File stream with errors, if any.

選項一：使用 Viva Insights 人力資源資料輸入 API 來建立自訂的匯入/匯出應用程式

你可以使用 Viva Insights 的人力資源資料輸入 API，建立一個自訂應用程式，自動從你的來源系統匯出資料，然後匯入到 Viva Insights。

你的應用程式可以是任何形式——例如PowerShell腳本——但它需要依你選擇的頻率匯出原始資料，將壓縮檔儲存在檔案中，並匯入Viva Insights。

選項二：在匯出資料後，透過我們的 C# 解決方案匯入資料，並透過自訂應用程式匯入資料

當你將來源資料匯出為你選擇的頻率的壓縮檔後，並將該資料夾存入檔案中，你可以在主控台上執行 DescriptiveDataUploadApp 的 C# 解決方案。 DescriptiveDataUploadApp C# 解決方案會將你本地儲存的資料帶到 Viva Insights。更多資訊請見 GitHub。

執行解法：

透過命令列執行以下指令，將此應用程式複製到你的電腦：

git clone https://github.com/microsoft/vivainsights_ingressupload.git.
請包含以下控制台數值。請參閱準備、匯出及匯入組織資料的說明。
- AppID/ClientID
- 壓縮檔的絕對路徑。路徑格式如下： C:\\Users\\JaneDoe\\OneDrive - Microsoft\\Desktop\\info.zip
- Microsoft Entra tenant ID
- 憑證名稱

選項三：透過自訂應用程式匯出資料後，執行 DescriptiveDataUpload PowerShell 解決方案

和選項二類似，當你把來源資料匯出成你選擇的頻率的壓縮檔，並將該資料夾存進檔案後，你可以在主控台上執行 DescriptiveDataUpload PowerShell 解決方案。 DescriptiveDataUpload PowerShell 解決方案會將你本地儲存的資料帶入 Viva Insights。更多資訊請見 GitHub。

透過命令列執行這個指令，將原始碼複製到你的電腦：

git clone https://github.com/microsoft/vivainsights_ingressupload.git
以系統管理員身分開啟新的 PowerShell 視窗。
在你的 PowerShell 視窗中，執行以下指令：

Install-Module -Name MSAL.PS

或者，可以參考這個 PowerShell 畫廊連結，了解安裝說明。
設定參數。請參閱準備、匯出及匯入組織資料的說明。
- ClientID
- pathToZippedFile
- TenantId
- novaScaleUnit
- ingressDataType: HR
- ClientSecret 或 certificateName

選項四：使用我們的 Azure Data Factory (ADF) 模板將資料傳送到基於 API 的匯入中

1. Create new Azure Data Factory

登入 https://adf.azure.com/en/datafactories。
建立新的資料工廠或使用現有的資料工廠。填寫欄位後，選擇建立。

2. 建立新的流程與活動

建立一條新的管線並輸入該管線的名稱。
在活動中新增 複製資料。

3. 複製資料活動設定：一般

選擇您的 複製資料 活動，然後依照下方指引選擇 「一般 」來完成每個欄位。

截圖顯示如何複製資料活動設定。

姓名：輸入你的活動名稱。
說明：輸入你的活動描述。
活動狀態：選擇啟用。或者選擇停用，以排除該活動進入管線執行與驗證。
暫停時間：這是活動可以執行的最大時間。預設時間為12小時，最短為10分鐘，最長允許時間為七天。格式採用D.HH：MM：SS。
重試次數：最多重試次數。這可以保持為 0。
重試間隔 (秒) ：最大重試次數。若重試次數設為 0，則該值可保持為 30。
安全輸出：選擇活動時，該活動的輸出不會被記錄在日誌中。你可以把這裡清空。
安全輸入：選擇活動時，該活動的輸入不會被記錄在日誌中。你可以把這裡清空。

4. 複製資料活動設定：來源

選擇來源。
選擇現有的來源資料集，或選擇 +New 以建立新的來源資料集。例如，在新資料集中選擇 Azure Blob 儲存體，然後選擇資料的格式類型。
設定 .csv 檔案的屬性。輸入名稱，並在 連結服務中選擇現有地點或選擇 +New。
如果您選擇 了+新，請依照下方指引輸入新連結服務的詳細資訊。
在「 來源資料集」旁邊，選擇 「開啟」。
選擇 「第一列」作為標頭。

5. 複製資料活動設定：匯入

選擇水槽。
選擇 +New 以設定新的 REST 資源以連接 Viva Insights 匯入 API。搜尋「休息」並選擇繼續。
說服務名稱。在 連結服務 中選擇 +New。
搜尋「休息」並選擇它。
請依照下方指引輸入欄位。

名稱：輸入你新連結服務的名稱。
說明：輸入您新連結服務的說明。
透過整合執行時連接：輸入偏好方法。
基礎網址：請使用下方網址，並將TENANT_ID>替換<成您的租戶 ID：https://api.orginsights.viva.office.com/v1.0/scopes/<TENANT_ID>/入口/連接器/人力資源/ingestions/fileIngestion
認證類型：選擇您的認證類型為 服務主體 或憑證。服務負責人範例：
- 內線：選擇它。
- 服務負責人識別碼：輸入該識別碼。
- 服務主鑰：輸入鑰匙。
- 房客：輸入房客編號。
- Microsoft Entra ID 資源：https://api.orginsights.viva.office.com
- Azure cloud type： Select your Azure cloud type.
- 伺服器憑證驗證：選擇啟用。

請依照下方指引輸入水槽設定。

匯集資料集：選擇現有或新建立的資料集。
請求方式：選擇 POST。
請求超時：預設為五分鐘。
請求間隔為 (毫秒) ：10為預設值。
寫入批次大小：批次大小應該大於檔案中最大行數。
Http 壓縮類型：預設為 None。或者你也可以用 GZip。
額外標頭：選擇 +New。
- 盒子 1：x-nova-scaleunit
- 值：可透過 ->組織資料標籤頁 選 -> 選擇 管理資料來源 -> 選擇 基於 API 的匯入，從 Workplace Analytics 取得該值。

6. 複製資料活動設定：映射

選擇映射。
在 bootstrap 上傳時，請務必在目的地名稱) (映射中包含 PersonId、 ManagerID 和 Organization 。對於增量上傳，請確認目的地名稱與先前上傳的名稱一致，並確認 PersonId。你無法用新欄位進行增量上傳，且所有上傳都必須使用 PersonId 。

7. 複製資料活動設定：設定與使用者屬性

設定或使用者屬性不需要其他自訂。如果需要，你可以逐案編輯這些設定。

8. 複製資料活動：觸發設定 (自動化)

要在自動化設定中新增觸發器，請選擇 新增觸發器。建議的自動化是每週一次。你也可以自訂頻率。

截圖顯示如何設定觸發器。

驗證

資料來源管理員傳送資料後，應用程式會開始驗證。

此階段結束後，驗證要麼成功，要麼失敗。根據結果，你會在 資料連線 畫面右上角收到成功通知或失敗通知。

關於接下來發生的事，請前往相關章節：

驗證成功

驗證失敗

驗證成功

驗證成功後，Viva Insights 會開始處理您的新資料。處理過程可能需要幾小時到一兩天不等。處理過程中， 匯入歷史 表上會出現「處理中」狀態。

處理完成後，要麼成功，要麼失敗。根據結果，你會在 匯入歷史 表中看到「成功」或「失敗」狀態。

處理成功

當你在 匯入歷史 表中找到「成功」狀態時，上傳流程就完成了。

當您獲得「成功」狀態後，您可以：

選擇「視 (眼) 圖示，即可查看驗證結果摘要。
選擇映射圖示以查看工作流程的映射設定。

注意事項

每個租戶一次只能有一個進行中的匯入。你需要完成一個資料檔案的工作流程，這表示你要麼引導它成功驗證與處理，要麼放棄它，然後再開始下一個資料檔案的工作流程。上傳工作流程的狀態或階段會顯示在 資料連接 標籤上。

處理失敗

若處理失敗，匯 入歷史 表中會出現「處理失敗」狀態。為了讓處理成功，資料來源管理員必須修正錯誤，並將資料再次推送到 Viva Insights。

注意事項

處理失敗通常是因為後端錯誤。如果你發現持續的處理失敗，且你已修正匯入檔案中的資料，請向我們提交支援單。

驗證失敗

若資料驗證失敗，匯 入歷史 資料表中會出現「驗證失敗」狀態。為了讓驗證成功，資料來源管理員必須修正錯誤，並將資料再次推送到 Viva Insights。在 「操作」中，選擇下載圖示以下載錯誤日誌。將這份日誌傳給資料來源管理員，讓他們知道該修正什麼，再再傳送資料。

資料來源管理員可能會覺得以下章節有助於修正匯出檔案中的資料錯誤。

關於資料錯誤

適用於：資料來源管理員

當任何資料列或欄位的屬性值為無效時，整個匯入都會失敗，直到資料來源管理員修正該來源資料為止。

請參閱「準備組織資料」以了解可能有助於解決您遇到錯誤的具體格式規則。

了解更多關於驗證錯誤與警告的資訊。

準備組織資料

匯入組織資料 (後續匯入)

意見反應

此頁面對您有幫助嗎？

Last updated on 2026-01-16

共用方式為

使用 API 導向匯入匯入組織資料 (首次匯入) (預覽)

工作流程

安裝程式

產生安全憑證

Register a new app in Azure

在 Viva Insights 中設定匯入

準備、匯出及匯入組織資料

準備資料的技巧

匯出資料時設定頻率

data.csv

metadata.json

匯入你的資料

關於 Viva Insights 人力資源資料輸入 API

取得連接器/ping來檢查該連接器是否已設定為租戶

推送資料

投票狀態

如果驗證失敗 (資料) 問題，下載錯誤串流

選項一：使用 Viva Insights 人力資源資料輸入 API 來建立自訂的匯入/匯出應用程式

選項二：在匯出資料後，透過我們的 C# 解決方案匯入資料，並透過自訂應用程式匯入資料

選項三：透過自訂應用程式匯出資料後，執行 DescriptiveDataUpload PowerShell 解決方案

選項四：使用我們的 Azure Data Factory (ADF) 模板將資料傳送到基於 API 的匯入中

1. Create new Azure Data Factory

2. 建立新的流程與活動

3. 複製資料活動設定：一般

4. 複製資料活動設定：來源

5. 複製資料活動設定：匯入

6. 複製資料活動設定：映射

7. 複製資料活動設定：設定與使用者屬性

8. 複製資料活動：觸發設定 (自動化)

驗證

驗證成功

處理成功

處理失敗

驗證失敗

關於資料錯誤

相關主題

意見反應

其他資源