在 Azure DevOps 中使用服務主體自動化 Git 整合

Fabric Git 整合是組織實施全自動化 CI/CD 管線的基礎，使資產能在開發、測試與生產環境中無縫移動。

目前，Fabric Git 整合支援兩大主要的 Git 供應商：

Azure DevOps
GitHub

本文聚焦於 Azure DevOps 的服務主體（Service Principal）功能。此整合可讓 Fabric 使用者使用服務主體執行 Git 作業。

Azure DevOps：認證 - 自動且已設定

預設情況下，每個 Fabric 工作區都不會連接到任何 Git 儲存庫。 Fabric 工作區有兩種不同的方式可以驗證到 git 儲存庫。這些過程稱為：

自動生成的 git 憑證
已設定的憑證

自動 git 憑證

當管理員使用者想將工作空間連接到 Azure DevOps （ADO）儲存庫時，使用者必須先從工作區設定登入，系統會識別使用者在目前 Fabric 租戶中可存取的 ADO 組織，讓使用者能繼續設定。

一旦初始連線建立，任何在同一工作區至少擁有貢獻者權限的額外使用者，就不必重複連線流程。系統會嘗試以已設定的 ADO 儲存庫驗證第二位使用者。若使用者缺乏必要的權限，Fabric Git 整合的原始碼控制面板會顯示紅色指示器。

這種簡化的認證流程稱為「自動 Git 憑證」（Automatic Git Credential）。

已設定的憑證

有了已設定的憑證，你可以用服務主體程式化地建立 Azure DevOps 雲端連線。

Azure DevOps 連線支援兩種認證方式：

OAuth 2.0
服務主體

這兩種方法都支援多租戶（跨租戶）情境，讓組織在不同環境中具備彈性。

同一工作區至少有貢獻者權限的其他使用者，則不需要重複連線流程。在服務主體支援之前，系統僅嘗試透過 自動認證來驗證次要使用者。

若自動驗證失敗，系統也會嘗試使用使用者可存取的任何 已設定憑證 連線，確保更順暢的使用體驗並減少冗餘的設定步驟。

運作方式

若要將 Fabric 工作空間與外部 Git 供應商使用 Service Principal 連接，Git 整合必須使用類似 Azure DevOps – Source Control 的 Fabric 雲端連線。

這種雲端連線可以透過入口網站有兩種方式建立：

手動透過管理連線設定
在工作區設定中使用新增帳號選項

在這兩種情況下，連線都是以登入使用者的身份建立。

如果服務主體需要使用此連線，使用者必須

與服務主體共享連線
使用 Connections REST API 建立新連線，傳遞服務主體憑證。

以下步驟說明如何利用 API 透過服務主體建立雲端連線。

先決條件

要完成上述步驟，您需要取得以下權限：

註冊 Entra ID 應用程式並注意：
- 租戶識別碼
- 用戶端識別碼
- 用戶端密碼
授予服務負責人：
- 存取相關的 Azure DevOps 組織與專案。
- Fabric 工作區的管理員權限。

使用 Service Principal 連接新工作空間到 Azure DevOps

若要以程式方式使用 Service Principal 將 Fabric 工作空間連接到 Azure DevOps，需遵循以下步驟：

產生服務主體存取權杖： 透過服務主體與 Microsoft Fabric 進行認證。
Create Azure DevOps cloud connection： 在 Microsoft Fabric 中建立一個新的連線資源，用來儲存 Azure DevOps 倉庫的憑證和設定。
將工作空間連接到 git： 透過步驟 2 建立的連線，將特定的 Fabric 工作空間連結到 Azure DevOps 儲存庫。
初始化連線： 初始化 Git 連線。

1. 產生服務主體 (Service Principal) 存取權杖

以下範例說明如何產生服務主體存取權杖。

curl --request GET \ 
--url https://login.microsoftonline.com/<tenant-id>/oauth2/v2.0/token \ 
--header 'content-type: multipart/form-data' \ 
--form grant_type=client_credentials \ 
--form client_id=<client-id> \ 
--form 'client_secret=<client-secret>' \ 
--form scope=https://api.fabric.microsoft.com/.default

備註

請從回應中複製 access_token 以備後用。

2. 建立 Azure DevOps 雲端連線

在 Microsoft Fabric 中建立一個新的連線資源，用來儲存 Azure DevOps 倉庫的憑證和設定。

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 

"displayName": "<name of the connection>", 
"connectivityType": "ShareableCloud", 
"connectionDetails": { 
"creationMethod": "AzureDevOpsSourceControl.Contents", 
"type": "AzureDevOpsSourceControl", 
"parameters": [ 

{ 
"dataType": "Text", 
"name": "url", 
"value": "https://dev.azure.com/<ado org name>/<project name>/_git/<repo name>/"}]}, 
"credentialDetails": { 
"credentials": { 
"credentialType": "ServicePrincipal", 
"tenantId": "<tenant-id>", 
"servicePrincipalClientId": "<client-id>", 
"servicePrincipalSecret": "<client-secret>"}}}'

備註

把回覆裡的ID（身分證）保存下來。它會在接下來的步驟中使用。

3. 將工作空間連接到 git

透過步驟 2 建立的連線，將特定的 Fabric 工作空間連結到 Azure DevOps 儲存庫。

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/connect \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"gitProviderDetails": { 
"organizationName": "<ado org name>", 
"projectName": "<project name>", 
"gitProviderType": "AzureDevOps", 
"repositoryName": "<repo name>", 
"branchName": "<branch name>", 
"directoryName": "<folder name – must exist before OR empty>" 
}, 
"myGitCredentials": { 
"source": "ConfiguredConnection", 
"connectionId": "<step 2 – the new connection id>"}}'

4. 初始化連線

初始化連線，詳情請見此處。

備註

用你的值替換 <>，請注意 initializationStrategy 參數。如果連線的工作區中已經存在項目，你可以考慮使用「preferWorkspace」。

curl --request POST \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/initializeConnection \ 
--header 'authorization: Bearer <step1: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{"initializationStrategy": "PreferRemote"}'

如果倉庫 /workspace 不是空的，系統回應將會返回 requiredAction 參數（這是根據您的初始化策略決定的）。請分別使用 update-from-git 或 commit-to-git。利用回應中的 workspaceHead 和 remoteCommitHash 來完成這個流程。

連接現有工作區以使用 Service Principal

如果你的工作空間已經透過使用者身份連接到 Azure DevOps，但你想用服務主體執行 Fabric Git REST API 操作，請遵循以下步驟：

將服務主體新增為工作區管理員。
將服務主體的存取權限授予 Azure DevOps 雲端連線。您有兩個選擇：

分享現有的連結： 請以有權限存取相關 ADO 雲端連線的使用者登入，並透過管理使用者與服務主體分享。
建立新的連結： 重複前一節的步驟 1 和 2，使用 Service Principal 憑證建立新的雲端連線。

驗證存取權限 - 呼叫 GET Connections API 以確認服務主體是否能存取所需的雲端連線：

curl --request GET \ 
--url https://api.fabric.microsoft.com/v1/connections \ 
--header 'authorization: Bearer <step 2: access-token>'

從回應中取得相關連線的 id 值。

更新 Git 憑證：產生 一個存取權杖 （前一節的第一步），並呼叫 更新我的 Git 憑證 API，詳情請見此處（用你的值替換 <> ）：

curl --request PATCH \ 
--url https://api.fabric.microsoft.com/v1/workspaces/<workspace-id>/git/myGitCredentials \ 
--header 'authorization: Bearer <step 2: access-token>' \ 
--header 'content-type: application/json' \ 
--data '{ 
"source": "ConfiguredConnection", 
"connectionId": "<step 3: connection id>"}'

完成這些步驟後，服務主體即可完整配置並準備執行 Fabric Git REST API 操作。

意見反應

此頁面對您有幫助嗎？

Last updated on 2025-12-17