開始使用 Git 整合

本文將帶你了解 Microsoft Fabric Git 整合工具中的基本任務：

• 連接到 Git 存放庫
• 提交變更
• 從 Git 更新
• 中斷與 Git 的連線

建議您先閱讀 Git 整合的概觀 ，再開始。

必要條件

要將 Git 整合到 Microsoft Fabric 工作空間，你需要為 Fabric 和 Git 設定以下先決條件。

Fabric 先決條件

要存取 Git 整合功能，你需要 Fabric 容量。 需要 Fabric 容量才能使用所有受支援的 Fabric 元件。 如果您還沒有，請報名免費試用。 已經有 Power BI Premium 容量的客戶可以使用該容量，但請記住 ，某些 Power BI SKU 只支援 Power BI 專案。

此外，必須透過管理入口網站啟用下列租戶開關：

• 使用者可以建立 Fabric 項目 - 在使用 Fabric 工件時，這是必須的
• 用戶可以同步工作區項目與其 Git 存放庫
• 建立工作區 （只有在您想要分支至新的工作區時。
• 用戶可以與GitHub的儲存庫同步工作區項目：僅限GitHub使用者使用

視 貴組織的設定而定，租用戶系統管理員、容量管理員或工作區管理員可以啟用這些交換器。

Git 必要條件

Git 整合目前支援 Azure DevOps 和 GitHub。 要在 Fabric 工作空間中使用 Git 整合，你需要在 Azure DevOps 或 GitHub 中完成以下內容：

Azure DevOps 限制

• 在同一位 Fabric 使用者名下註冊的有效 Azure DevOps 帳號（即使 Azure DevOps 組織與 Fabric 租戶屬於不同租戶，Azure 仍然提供支援）。 建立免費帳號。
• 存取既有的儲存庫。

GitHub 限制

• 一個活躍的 GitHub 帳號。 建立一個GitHub帳號。

• 其中一個個人存取權杖：

  • 一個細粒度的標記（推薦），在儲存庫權限下有Contents的讀寫權限：

    

    要使用此代幣GitHub Enterprise，請遵循這些指示。

  • 建立一個啟用 repo 權限的 GitHub 經典權杖：

    GitHub 經典權杖範圍的截圖。

將工作區連線至 Git 存放庫

連接到 Git 存放庫

只有工作區管理員可以將工作區連線到存放庫，但一旦連線，任何具有 許可權 的任何人都可以在工作區中工作。 如果您不是管理員，請向管理員尋求連線方面的協助。 要將工作空間連接到 Azure 或 GitHub 倉庫，請依照以下步驟操作：

1. 登入 Fabric 並瀏覽至您想要連線的工作區。

2. 前往 [工作區設定]

   

3. 選擇 Git 整合。

4. 選取 Git 提供者。 目前支援 Azure DevOps 和 GitHub。

Azure DevOps Connect

如果您選擇 Azure DevOps，請選擇 Connect 以自動登入已登錄於 Microsoft Entra 使用者的 Azure Repos 帳戶。

如果你已經用其他帳號登入 Fabric Azure，請從清單中選擇你的帳號，然後選擇 Connect。

如果您是第一次從 Fabric 登入，或您想要新增帳戶，請選取 [ 新增帳戶]。

如果是第一次連線，您需要授權您的使用者。 提供下列資訊：

• 顯示名稱 - 每個使用者都必須是唯一的
• Azure DevOps URL - Azure DevOps 倉庫的網址。 網址格式必須為 https://dev.azure.com/{organization}/{project}/_git/{repository} 或 https://{organization}.visualstudio.com/{project}/_git/{repo}。
• 驗證 - 您可以使用 OAuth2 或 服務主體進行驗證。 更多資訊請參閱 Azure DevOps - Git 與服務主體的整合

登入後，選擇 Connect 以讓 Fabric 存取您的帳號

GitHub Connect

如果你選擇 GitHub，你需要登入你的 GitHub 帳號。 如果你已經登入 GitHub，請從列表中選擇你的帳號，並選擇 Connect。

如果您是第一次從 Fabric 登入，或您想要新增帳戶，請選取 [ 新增帳戶]。

如果是第一次連線，你需要授權你的 GitHub 帳戶Authorize。 提供下列資訊：

• 顯示名稱 - 必須對每位GitHub使用者獨一無二
• 個人存取權杖 - 你的經典或細粒度個人存取權杖
• Repository URL（github.com 可選，ghe.com 必須）- 如果你不輸入 URL，你可以連接到任何你有權限的 github.com 倉庫。 如果您輸入網址，則只能連線到該存放庫。

登入後，選擇 Connect 以便讓 Fabric 存取你的 GitHub 帳號。

連線到工作區

如果工作空間已經連接到 Azure DevOps/GitHub，請依照 連接到共享工作空間 的指示操作。

連接 Azure DevOps 分支

1. 從下拉式功能表中指定您要連線之分支的下列詳細資料：

   • 組織
   • Project
   • Git repository。
   • 分支 (使用下拉式功能表選取現有分支，或選取[+ 新增分支]以建立新的分支。您一次只能連線到一個分支。)
   • 資料夾 （輸入現有資料夾的名稱，或輸入名稱以建立新資料夾。如果您將資料夾名稱保留空白，則會在根資料夾中建立內容。您一次只能連線到一個資料夾。

GitHub 分支連接

1. 從下拉式功能表中指定您要連線之分支的下列詳細資料：

   • Repository 網址。 如果你使用範圍權杖連線到 GitHub，網址會自動填入，你只能連線到該資料庫。
   • 分支 (使用下拉式功能表選取現有分支，或選取[+ 新增分支]以建立新的分支。您一次只能連線到一個分支。)
   • 資料夾 （輸入現有資料夾的名稱，或輸入名稱以建立新資料夾。如果您將資料夾名稱保留空白，則會在根資料夾中建立內容。您一次只能連線到一個資料夾。

選取 [連線和同步]。

在初始同步處理期間，如果工作區或 Git 分支為空，則會將內容從非空位置拷貝到空位置。 如果工作區和 Git 分支均有內容，系統會詢問同步應遵循的方向。 如需此初始同步處理的詳細資訊，請參閱 連線和同步處理。

連線之後，工作區會顯示原始檔控制的相關信息，可讓用戶檢視已連線的分支、分支中每個項目的狀態，以及上次同步的時間。

若要讓工作區與 Git 分支保持同步，請提交您在工作區中所做的 任何變更 至 Git 分支，並在任何人建立新的提交至 Git 分支時 更新您的工作區。

將變更提交至 git

成功連線到 Git 資料夾之後，請如往常一樣編輯工作區。 您儲存的任何變更只會儲存在工作區中。 準備就緒之後，您可以將變更認可至 Git 分支，也可以復原變更並還原為先前的狀態。

深入了解 提交。

提交至 Git

若要將變更認可至 Git 分支，請遵循下列步驟：

1. 前往工作區。

2. 選取 [原始檔控制] 圖示。 此圖示會顯示未認可的變更數目。

3. 從 版本控制 面板中選取 變更。 清單隨即出現，其中包含您變更的所有專案，以及指出專案是否為 新的 、 已 修改、 衝突 、 相同變更 或刪除 的圖示 。

4. 選取您要提交的項目。 若要選取所有項目，請選取頂端方塊。

5. 在框中新增註解。 如果您未新增註解，系統會自動新增預設訊息。

6. 選擇 提交。

   

提交變更後，已提交的變更項目會從清單中移除，工作區會指向已同步的新提交。

成功完成認可之後，所選取的項目的狀態會從 [未認可] 變更為 [已同步]。

提交到獨立分支

「提交到獨立分支」是 Git 的一個整合功能，讓你能建立一個全新的分支，並在一個動作中提交你目前的變更。 換句話說，你不必承諾已連接的分支，而是可以隨時分支：系統會啟動新的 Git 分支，並儲存你的工作，無需你離開或切換原分支。

1. 前往工作區。
2. 選取 [原始檔控制] 圖示。 此圖示會顯示未認可的變更數目。
3. 從 版本控制 面板中選取 變更。 清單隨即出現，其中包含您變更的所有專案，以及指出專案是否為 新的 、 已 修改、 衝突 、 相同變更 或刪除 的圖示 。
4. 選取您要提交的項目。 若要選取所有項目，請選取頂端方塊。
5. 在框中新增註解。 如果您未新增註解，系統會自動新增預設訊息。
6. 選擇 「提交至新分支」。

重要

請注意下列事項：

• 新建立的分支不會連接到現有的工作區。
• 新建立的分支將基於目前工作區的最後同步狀態。
• 當有更新進來時，即使預設提交被停用，這項功能仍可實現。
• 目前的工作區狀態不會因為這次提交而改變，保持不變。

復原儲存的變更

將變更儲存至工作區之後，如果您決定不想將這些變更認可至 git，您可以復原變更，並將這些專案還原為先前的狀態。 若要復原變更，請按照下列步驟執行：

1. 前往工作區。

2. 選取 [原始檔控制] 按鈕。 此按鈕也會顯示未認可的變更的數目。

3. 從原始碼控制面板選取變更。 清單隨即出現，其中包含您變更的所有專案，以及指出變更的專案是否為 新的 、 已 修改、 衝突 或刪除 的圖示 。

4. 選取您想要復原的變更。

5. 在 [我瞭解工作區專案可能已刪除且無法還原 ] 方塊中勾選，然後選取 [ 復原]。

   

6. 再次選取 復原 以確認。 您看到的對話方塊可能會有所不同，具體取決於是否偵測到將要刪除的項目。 第一個螢幕截圖顯示沒有刪除。 第二個，如果偵測到刪除。

   

   

工作區中已選取的項目會還原為工作區上次同步時的狀態。

重要

如果您刪除項目，然後復原變更，則會建立新的項目，且部分中繼資料可能會遺失。 例如，敏感度標籤不會保留且應該重設，且項目的擁有者會設定為目前使用者。

還原已新增的項目會永久刪除該項目。

從 Git 更新工作區

每當有人提交新的變更到連結的 Git 分支時，相關工作區中就會顯示通知。 使用 [原始檔] 控制面板 來提取最新的變更、合併或還原到工作區並更新實時專案。 對資料夾的變更也會進行更新。 閱讀更多關於 更新。

若要更新工作區，請按照下列步驟執行：

1. 前往工作區。
2. 選取 [原始檔控制] 圖示。
3. 從來源控制面板中選擇 更新。 隨即出現一個清單，其中包含自上次更新以來分支中已變更的所有項目。
4. 選擇 全部更新。

5. 在確認對話框中，選擇 更新。

更新成功後，會移除清單，而工作區將指向同步至的新工作區。

成功完成更新之後，項目的狀態會變更為 [已同步]。

中斷工作區與 Git 的連線

只有工作區管理員可以中斷工作區與 Git 存放庫的連線。 如果您不是管理員，請向管理員尋求中斷連線方面的協助。 如果您是管理員，並且想要中斷存放庫的連線，請按照下列步驟執行：

1. 前往 [工作區設定]
2. 選取 Git 整合功能。
3. 選擇 斷開工作區
4. 再次選取 [中斷連線] 以確認。

權限

您可以對工作區採取的動作取決於您在工作區和 Git 存放庫中擁有的權限。 如需許可權的詳細討論，請參閱 許可權。

考量與限制

Git 整合的常見限制

• Fabric 中的 驗證方法 至少必須和 Git 的驗證方法一樣強。 例如，如果 Git 需要多重要素驗證，Fabric 也需要多重要素驗證。
• 目前不支援連線至 Analysis Services 的 Power BI 資料集。
• 如果您在某個工件中使用工作區身分識別並將其提交至 Git，則只能在連線至相同身分識別的工作區中更新它（返回到一個網狀架構的工作區）。 請小心，因為這也會影響分支輸出之類的功能。
• 不支援子模組。
• 不支援主權雲端服務。
• 如果你的工作區有數百個項目，可以考慮將其拆分成更小的工件集合。 每組應該放置在獨立的工作空間中，並鏈接到不同的 Git 分支，或連接到在不同資料夾中組織的單一分支。

Azure DevOps 限制

• Azure DevOps 在啟用 Enable IP 條件式存取政策驗證 時不受支援。
• 如果工作區和 Git 存放庫位於兩個不同的地理區域，租用戶系統管理員必須啟用 跨地理位置匯出。
• 如果您的組織設定了 條件式存取，請確保 Power BI 服務具備相同的 條件設定，以確保身份驗證能如預期運作。
• 以下是適用的提交大小限制：
  • 25 MB 透過 Service Principal 使用 Azure DevOps 連接器。
  • 125 MB 使用預設的單一登入（SSO）Microsoft Entra ID 帳號及 Azure DevOps 連接器與 User Principal。

GitHub 限制

• 僅支援雲端版本的 GitHub。 不提供對本地端的支援。
• GitHub無法強制執行 跨地理驗證。
• 一次提交的檔案總大小限制為 50 MB。 因此，如果您有多個項目需要提交，有時可能需要將它們分成幾個獨立的提交紀錄。 如需提交檔案的詳細資訊，請參閱我們的 疑難解答指南。

GitHub Enterprise 限制

部分 GitHub Enterprise 版本和設定不支援。 例如：

• 即使該實例是公開存取的，GitHub Enterprise Server 也不支援自訂網域。
• GitHub 企業伺服器託管於私人網路
• IP 允許清單

Azure DevOps to GitHub Enterprise 遷移考慮

如果您的團隊使用 Fabric Git 整合，並正在評估從 Azure DevOps 遷移到 GitHub Enterprise，建議執行驗證測試以確保 Git 整合功能不受影響。 Fabric Git 整合依賴底層的 Git 提供者 API，這些 API 在 Azure DevOps 與 GitHub Enterprise 之間的能力與限制有所不同，如上所述。

工作區限制

• 只有工作區管理員能管理與 Git Repo 的連線，例如連接、斷開或新增分支。
  連線之後，具有 許可權 的任何人都可以在工作區中工作。
• 已安裝範本應用程式的工作區無法連線到 Git。
• MyWorkspace 無法連線到 Git 提供者。
• 工作區最多可容納 1,000 件物品。 如果 Git 分支包含超過 1,000 個項目，將內容同步到工作區時會失敗。 為了避免這個限制，可以考慮將你的 artifacts 拆分成較小的組合。 每個集合應該放在獨立的工作區並連結到不同的 Git 分支，或整理到同一個分支內的不同資料夾。 欲進一步閱讀， 請參考工作區項目限制。

分支和資料夾限制

• 分支名稱長度上限為 244 個字元。
• 檔案名稱的完整路徑長度上限為 250 個字元。 較長的名稱會失敗。
• 檔案大小上限為 25 MB。
• 資料夾結構最多可達到10個層級深。
• 不建議在使用 Git 整合部署報表/數據集後，從服務下載為 .pbix ，因為結果不可靠。 我們建議使用 Power BI Desktop 下載報表/資料集，格式為 .pbix。
• 如果項目的顯示名稱具有下列任何特性，Git 資料夾會重新命名為邏輯識別碼 （Guid） 並輸入：
  • 字元數超過 256 個
  • 結尾是 。 或空格
  • 包含任何禁止字元，這些字元已在目錄名稱限制中有所描述
• 當您將具有資料夾的工作區連線到 Git 時，如果該 資料夾結構 不同，則必須將變更提交到 Git 存放庫。

目錄名稱限制

• 線上至 Git 存放庫的目錄名稱具有下列命名限制：

  • 目錄名稱不能以空格或標籤開頭或結尾。
  • 目錄名稱不能包含下列任何字元：“/：<>\*|

• 專案資料夾（包含專案檔案的資料夾）不能包含下列任何字元： “：<>\*？|。 如果您將資料夾重新命名為包含這些字元之一的名稱，則 Git 無法連線或同步處理工作區，並發生錯誤。

分支限制

• 拓展需要許可權數據表中列出的許可權。
• 必須有可用的容量才能執行此動作。
• 所有 工作區 和 分支命名限制 都會在分支至新的工作區時套用。
• 新的工作區中僅提供 Git 支援的專案 。
• 相關的分支清單僅顯示您有權檢視的分支和工作區。
• 必須啟用 Git 整合。
• 擴展分支時，會建立新的分支，並且不會複製原始分支中的設定。 調整任何設定或定義，以確保新符合貴組織的原則。
• 擴展到現有工作區時：
  • 目標工作區必須支援 Git 連線。
  • 用戶必須是目標工作區的管理員。
  • 目標工作區必須具有容量。
  • 工作區不能有範本應用程式。
• 請注意，當您分支至工作區時，未儲存至 Git 的任何項目都會遺失。 建議您在分支之前提交任何您想要保留的項目。

同步與提交限制

• 你一次只能同步一個方向。 無法同時提交和更新。
• 不支援敏感度標籤，並且可能會停用匯出具有敏感度標籤的項目。 若要提交沒有敏感度標籤的專案，請向系統管理員尋求協助。
• 適用於 有限的項目。 資料夾中不受支援的項目會略過。
• 不允許複製名稱。 即使 Power BI 允許重複名稱，更新、認可或復原動作也會失敗。
• 不支援 B2B。
• 衝突解決 是在 Git 中部分完成的。
• 在 認可 Git 程式期間，Fabric 服務會刪除不屬於專案定義之 專案資料夾內的 檔案。 不會刪除不在項目資料夾中的非相關檔案。
• 提交變更之後，您可能會注意到項目有一些您自己未做的非預期變更。 這些變更在語意上無關緊要，且可能存在多個原因。 例如：
  • 手動變更項目定義檔案。 這些變更有效，但可能不同於透過編輯器完成的變更。 例如，如果您在 Git 中重新命名語意模型的欄位，並將此變更匯入工作區，當您下一次提交語意模型的變更時，bim 檔案將會被註冊為已變更，且修改過的欄位會被推至陣列的末端columns。 這是因為產生 bim 檔案的 AS 引擎會將重新命名的數據行推送至陣列結尾。 這項變更不會影響項目的運作方式。
  • 提交一個使用 CRLF 換行符的檔案。 服務使用 LF （換行符） 進行換行。 如果您在 Git 存放庫中有使用 CRLF 換行符的檔案，當您從服務提交這些檔案時，這些檔案會被改為 LF。 例如，如果你在桌面端開啟報表，儲存project檔案（.pbip），並用 CRLF 上傳到 Git。
• 使用增強式重新整理 API 重新整理語意模型，會在每次重新整理之後產生 Git 差異。

相關內容

• 瞭解 Git 整合程式
• 管理 Git 分支
• Git 整合最佳做法