建立和管理代理程式組件區

Azure DevOps Services |Azure DevOps Server 2022 - Azure DevOps Server 2019 |TFS 2018

注意

在 Microsoft Team Foundation Server (TFS) 2018 和舊版中，組建和發行管線稱為定義、執行稱為組建、服務連線稱為服務端點、階段稱為環境，而作業稱為階段。

代理程式組件區是代理程式的集合。 您不需要個別管理每個 代理程式 ，而是將代理程式組織成 代理程式組件區。 在 TFS 中，集區的範圍是整個伺服器;因此，您可以跨專案集合和專案共用代理程式組件區。

代理程式佇列可讓您存取專案中的代理程式組件區。 當您建立組建或發行管線時，您可以指定它所使用的佇列。 佇列的範圍僅限於 TFS 2017 和更新版本中的專案，因此您只能在專案的組建和發行管線之間使用這些佇列。

若要與多個專案共用代理程式組件區，請在每個專案中建立指向相同代理程式組件區的代理程式佇列。 雖然跨專案的多個佇列可以使用相同的代理程式組件區，但專案中的多個佇列無法使用相同的代理程式組件區。 此外，每個代理程式佇列只能使用一個代理程式組件區。

代理程式組件區是代理程式的集合。 您不需要個別管理每個 代理程式 ，而是將代理程式組織成代理程式組件區。 當您設定代理程式時，它會向單一集區註冊，而當您建立管線時，您會指定管線執行所在的集區。 當您執行管線時，它會在該集區中符合管線 需求的 代理程式上執行。

在 Azure Pipelines 中，集區的範圍是整個組織;因此，您可以跨專案共用代理程式機器。

在Azure DevOps Server中，代理程式組件區的範圍是整個伺服器;因此您可以跨專案和集合共用代理程式機器。

注意

代理程式組件區作業會在單一代理程式上執行作業。 如果您需要在所有代理程式上執行作業，例如傳統發行管線的部署群組，請參閱 布建部署群組。

您可以從系統管理員設定中的 [代理程式組件區] 索引標籤建立和管理代理程式組件區。

如果您是組織系統管理員，您可以從系統管理員設定中的 [代理程式組件區] 索引標籤建立和管理代理程式組件區。

1. 選擇 [Azure DevOps]、 [組織設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 流覽至您的專案，然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

   

2. 選擇 [管理集區]。

   

您可以從專案設定中的 [代理程式佇列] 索引標籤建立和管理代理程式佇列。

如果您是專案小組成員，您可以從專案設定中的 [代理程式組件區] 索引標籤建立和管理代理程式佇列。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

預設代理程式組件區

預設會提供下列代理程式組件區：

• 預設 集區：使用它來註冊您已設定 的自我裝載代理程式 。

• 具有各種 Windows、Linux 和 macOS 映射的Azure Pipelines裝載集區。 如需可用映射及其已安裝軟體的完整清單，請參閱 Microsoft 裝載的代理程式。

  注意

  Azure Pipelines 裝載集區會取代先前裝載的集區，該集區的名稱對應至對應的映射。 您在先前裝載集區中擁有的任何作業都會自動重新導向至新 Azure Pipelines 裝載集區中的正確映射。 在某些情況下，您可能仍會看到舊的集區名稱，但在幕後，裝載的作業會使用 Azure Pipelines 集區來執行。 如需詳細資訊，請參閱2019 年 7 月 1 日 - 短期衝刺 154 版本資訊中的單一裝載集區版本資訊。

根據預設，專案中的所有參與者都是託管集區上 使用者 角色的成員。 這可讓專案中的每個參與者使用 Microsoft 裝載的代理程式來撰寫和執行管線。

在管線中指定集區

YAML

Azure DevOps Server 2019 和更新版本中支援 YAML 管線。

若要從您Azure DevOps Services YAML 管線中的 Azure Pipelines 集區中選擇 Microsoft 裝載的代理程式，請使用下表中的YAML VM 映射標籤來指定映射的名稱。

pool:
  vmImage: ubuntu-latest # This is the default if you don't specify a pool or vmImage.

若要使用私用集區，但不需要：

pool: MyPool

如需詳細資訊，請參閱集區的YAML 架構。

傳統

若要在傳統編輯器中選擇集區和代理程式，請流覽至管線設定，選取所需的 Agent 集區，然後從 [ 代理程式規格 ] 下拉式清單中選取所需的映射。 預設 代理程式規格 為 windows-2019。 如需 Microsoft 裝載映射上安裝之軟體的詳細資訊，請參閱下表中傳統編輯器集區資料行中的對應專案。

管理集區和佇列

瀏覽器

您可以從系統管理員設定中的 [代理程式組件區] 索引標籤建立和管理代理程式組件區。

如果您是組織系統管理員，您可以從系統管理員設定中的 [代理程式組件區] 索引標籤建立和管理代理程式組件區。

1. 選擇 [Azure DevOps]、 [組織設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 流覽至您的專案，然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

   

2. 選擇 [管理集區]。

   

您可以從專案設定中的 [代理程式佇列] 索引標籤建立和管理代理程式佇列。

如果您是專案小組成員，您可以從專案設定中的 [代理程式組件區] 索引標籤建立和管理代理程式佇列。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [專案設定]、[ 代理程式組件區]。

流覽至您的專案，然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

Azure DevOps CLI

列出代理程式組件區 | 顯示代理程式組件區詳細資料 | 列出代理程式佇列 | 顯示代理程式佇列詳細資料

注意

此時，您可以使用 Azure CLI 來檢視代理程式組件區和佇列的相關資訊，但無法加以編輯。

如果這是您第一次使用 az devops pipelines 命令，請參閱 開始使用 Azure DevOps CLI。

列出代理程式組件區

az pipelines pool list [--action {manage, none, use}]
                       [--detect {false, true}]
                       [--org]
                       [--pool-name]
                       [--pool-type {automation, deployment}]

參數

• action：篩選允許使用者動作的清單。 接受的值： manage、 none、 use
• detect：自動偵測組織。 接受的值： false、 true
• 組織 或 組織：Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。 如果未設定為預設或透過 git 組態挑選，則為必要專案。範例： https://dev.azure.com/MyOrganizationName/ 。
• pool-name：篩選具有相符集區名稱的清單。
• pool-type：篩選具有集區類型的清單。 接受的值： 自動化、 部署

範例

下列範例會列出資料表格式的所有集區。 此範例會使用下列預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber

az pipelines pool list --output table

ID    Name                             Is Hosted    Pool Type
----  -------------------------------  -----------  -----------
1     Default                          False        automation
2     Hosted                           True         automation
3     Hosted VS2017                    True         automation
4     Hosted Windows 2019 with VS2019  True         automation
5     Hosted Windows Container         True         automation
6     Hosted macOS                     True         automation
7     Hosted macOS High Sierra         True         automation
8     Hosted Ubuntu 1604               True         automation
9     Azure Pipelines                  True         automation
10    MyAgentPool                      False        automation

顯示代理程式組件區詳細資料

az pipelines pool show --id
                       [--action {manage, none, use}]
                       [--detect {false, true}]
                       [--org]

參數

• 識別碼 或 集區識別碼： (集區的必要) 識別碼，以列出詳細資料。
• action：篩選允許使用者動作的清單。 接受的值： manage、 none、 use
• detect：自動偵測組織。 接受的值： false、 true
• 組織 或 組織：Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。 如果未設定為預設或透過 git 組態挑選，則為必要專案。範例： https://dev.azure.com/MyOrganizationName/ 。

範例

下列範例會顯示具有 VS2019 集區的託管 Windows 2019 集區詳細資料。 此範例會使用下列預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber

az pipelines pool show --id 4

{
  "agentCloudId": 1,
  "autoProvision": true,
  "autoSize": null,

  <Some properties omitted for space>

  "poolType": "automation",
  "properties": null,
  "scope": "941fcaeb-be37-4309-b7b0-5cf156e1236e",
  "size": 1,
  "targetSize": 1
}

您也可以使用 --output table ，傳回與命令相同的資訊 list 。

az pipelines pool show --id 4 --output table

ID    Name                             Is Hosted    Pool Type
----  -------------------------------  -----------  -----------
4     Hosted Windows 2019 with VS2019  True         automation

列出代理程式佇列

az pipelines queue list [--action {manage, none, use}]
                        [--detect {false, true}]
                        [--org]
                        [--project]
                        [--queue-name]

參數

• action：篩選允許使用者動作的清單。 接受的值： manage、 none、 use
• detect：自動偵測組織。 接受的值： false、 true
• 組織 或 組織：Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。 如果未設定為預設或透過 git 組態挑選，則為必要專案。範例： https://dev.azure.com/MyOrganizationName/ 。
• 專案 或 p：專案的名稱或識別碼。 您可以使用 來設定預設專案 az devops configure -d project=NAME_OR_ID 。 如果未設定為預設或透過 git 組態挑選，則為必要專案。
• queue-name：篩選具有相符佇列名稱 RegEx 的清單，例如， ubuntu 用於名稱為 'Hosted Ubuntu 1604' 的佇列。

範例

下列範例會列出資料表格式的所有佇列。 此範例會使用下列預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber

az pipelines queue list --output table
This command group is in preview. It may be changed/removed in a future release.
ID    Name                             Pool IsHosted    Pool Type
----  -------------------------------  ---------------  -----------
11    Default                          False            automation
12    Hosted                           True             automation
13    Hosted VS2017                    True             automation
14    Hosted Windows 2019 with VS2019  True             automation
15    Hosted Windows Container         True             automation
16    Hosted macOS                     True             automation
17    Hosted macOS High Sierra         True             automation
18    Hosted Ubuntu 1604               True             automation
19    Azure Pipelines                  True             automation

顯示代理程式佇列詳細資料

az pipelines queue show --id
                        [--action {manage, none, use}]
                        [--detect {false, true}]
                        [--org]
                        [--project]

參數

• id 或 queue-id：要取得相關資訊的代理程式佇列識別碼。
• action：篩選允許使用者動作的清單。 接受的值： manage、 none、 use
• detect：自動偵測組織。 接受的值： false、 true
• 組織 或 組織：Azure DevOps 組織 URL。 您可以使用 az devops configure -d organization=ORG_URL 來設定預設組織。 如果未設定為預設或透過 git 組態挑選，則為必要專案。範例： https://dev.azure.com/MyOrganizationName/ 。
• 專案 或 p：專案的名稱或識別碼。 您可以使用 來設定預設專案 az devops configure -d project=NAME_OR_ID 。 如果未設定為預設或透過 git 組態挑選，則為必要專案。

範例

下列範例會顯示具有 VS2019 佇列之託管 Windows 2019 的佇列詳細資料。 此範例會使用下列預設組態： az devops configure --defaults organization=https://dev.azure.com/fabrikam-tailspin project=FabrikamFiber

az pipelines queue show --id 14

{
  "id": 14,
  "name": "Hosted Windows 2019 with VS2019",
  "pool": {
    "id": 4,
    "isHosted": true,
    "isLegacy": true,
    "name": "Hosted Windows 2019 with VS2019",
    "poolType": "automation",
    "scope": "941fcaeb-be37-4309-b7b0-5cf156e1236e",
    "size": 1
  },
  "projectId": "16836457-4ce1-4e77-b97a-e7e0c6508e84"
}

內部部署Azure DevOps Server不支援 Azure DevOps CLI 命令。

集區用於執行作業。 了解如何為作業指定集區。

如果您有許多適用于不同小組或用途的自我裝載代理程式，您可能會想要建立其他集區，如下所述。

建立代理程式集區

以下是您可能想要建立自我裝載代理程式組件區的一些典型情況：

• 您是專案的成員，而且您想要使用小組所擁有的一組機器來執行組建和部署作業。 首先，在專案設定的 [代理程式組件區] 頁面上選取 [ 安全性 ]，確定您已擁有在專案中建立集區的許可權。 您必須具備 系統管理員 角色，才能建立新的集區。 接下來，選取 [新增集 區]，然後選取選項以在組織層級建立 新的 集區。 最後 ，安裝 並設定代理程式成為該代理程式組件區的一部分。

• 您是基礎結構小組的成員，而且想要設定代理程式集區以用於所有專案。 首先，請流覽至組織設定中的 [代理程式組件區] 頁面，確定您是 [ 所有代理程式組件 區] 中具有 系統管理員 角色的群組成員。 接下來，建立 新的代理程式組件區 ，然後在建立集區時，選取在所有 專案中自動布建對應代理程式組件 區的選項。 此設定可確保所有專案都能存取此代理程式組件區。 最後 ，安裝 並設定代理程式成為該代理程式組件區的一部分。

• 您想要與多個專案 (而非所有專案) 共用一組代理程式電腦。 首先，流覽至其中一個專案的設定、新增代理程式組件區，然後選取選項以在組織層級建立 新的 集區。 接下來，移至其他每個專案，並在選取 [ 從組織使用現有的代理程式組件區] 選項時，在每個專案中建立集區。 最後， 安裝 並設定代理程式成為共用代理程式組件區的一部分。

• 您是專案的成員，而且您想要使用小組所擁有的一組機器來執行組建和部署作業。 首先，請確定您是所有 集 區中具有 系統管理員 角色的群組成員。 接下來，在專案設定中建立 新的專案代理程式組件區 ，然後選取 [ 建立新的組織代理程式組件區] 選項。 於是，您會建立組織層級和專案層級的代理程式集區。 最後 ，安裝 並設定代理程式成為該代理程式組件區的一部分。

• 您是基礎結構小組的成員，而且想要設定代理程式集區以用於所有專案。 首先，請確定您是所有 集 區中具有 系統管理員 角色的群組成員。 接著，在系統管理員設定中建立 新的組織代理程式組件區 ，然後在建立集區時，選取 [ 在所有專案中自動布建對應的專案代理程式組件 區] 選項。 此設定可確保所有專案都有集區指向組織代理程式集區。 系統會為現有專案建立集區，而未來每當建立新專案時，就會這麼做。 最後 ，安裝 並設定代理程式成為該代理程式組件區的一部分。

• 您想要與多個專案 (而非所有專案) 共用一組代理程式電腦。 請先在其中一個專案中建立專案代理程式組件區，然後選取在建立該集區時 建立新的組織代理程式組件 區選項。 接下來，移至其他每個專案，並在選取 [ 使用現有的組織代理程式組件區] 選項時，在每個專案中建立集區。 最後， 安裝和 設定代理程式成為共用代理程式組件區的一部分。

代理程式組件區的安全性

了解代理程式集區的安全性如何運作，可協助您控制代理程式的共用和使用。

角色 會定義在每個代理程式組件區上，而這些角色中的 成員資格 會控管您可以在代理程式組件區上執行的作業。

組織層級安全性設定

組織設定中代理程式組件區的角色	目的
讀取者	此角色的成員可以檢視代理程式組件區和代理程式。 您通常會使用此方法來新增負責監視代理程式及其健康情況的操作員。
服務帳戶	此角色的成員可以使用組織代理程式集區，在專案中建立專案代理程式集區。 如果您遵循上述指導方針來建立新的專案代理程式組件區，您通常不需要在此新增任何成員。
系統管理員	除了上述擁有權限之外，此角色的成員也可以從組織代理程式組件區註冊或取消註冊代理程式。 在專案中建立專案代理程式集區時，這些成員也可以參考組織代理程式集區。 最後，這些成員還可以管理組織代理程式集區所有角色的成員資格。 建立組織代理程式組件區的使用者會自動新增至該集區的系統管理員角色。

[代理程式組件區] 索引標籤中的 [ 所有代理程式組件 區] 節點可用來控制 所有 組織代理程式組件區的安全性。 個別組織代理程式組件區的角色成員資格會自動繼承自「所有代理程式組件區」節點的成員資格。 根據預設，使用 TFS 或Azure DevOps Server時，TFS 和Azure DevOps Server系統管理員也是「所有代理程式組件區」節點的系統管理員。

專案層級安全性設定

每個專案代理程式組件區上也會定義角色，而這些角色中的成員資格會控管您可以在專案層級的代理程式組件區上執行的作業。

專案設定中的代理程式組件區角色	目的
讀取者	此角色的成員可以檢視專案代理程式集區。 您通常會使用此方法來新增負責監視該專案代理程式組件區中建置和部署作業的操作員。
User	撰寫管線時，此角色的成員可以使用專案代理程式組件區。
系統管理員	除了上述所有作業之外，此角色的成員還可以管理專案代理程式組件區所有角色的成員資格。 建立集區的使用者會自動新增至該集區的管理員角色。

管線權限

管線許可權可控制哪些 YAML 管線有權使用代理程式組件區。 管線許可權不會限制來自傳統管線的存取。

您可選擇下列選項：

• 開啟所有管線的存取權，以從代理程式組件區安全性索引標籤的 [ 管線許可權 ] 區段右上角的更多選項使用代理程式組件區。

• 鎖定代理程式組件區，只允許選取的 YAML 管線使用它。 如果任何其他 YAML 管線參考代理程式組件區，就會引發授權要求，該要求必須由代理程式組件區管理員核准。 這不會限制從傳統管線存取。

Azure Pipelines 代理程式組件區的管線許可權無法設定，因為集區預設可供所有管線存取。

[代理程式組件區] 索引標籤中的 [ 所有代理程式 集區] 節點是用來控制專案中 所有 專案代理程式組件區的安全性。 個別專案代理程式組件區的角色成員資格會自動繼承自「所有代理程式組件區」節點的成員資格。 根據預設，下列群組會新增至「所有代理程式集區」的管理員角色：組建管理員、發行管理員、專案系統管理員。

[代理程式組件區] 索引標籤中的 [安全性 ] 動作可用來控制專案中 所有 專案代理程式組件區的安全性。 個別專案代理程式組件區的角色成員資格會自動繼承自您在這裡定義的專案。 根據預設，下列群組會新增至「所有代理程式集區」的管理員角色：組建管理員、發行管理員、專案系統管理員。

常見問題集

如果我未排程維護期間，代理程式何時會執行維護？

如果沒有排程任何視窗，則該集區中的代理程式將不會執行維護作業。

什麼是維護作業？

您可以將代理程式組件區設定為定期清除過時的工作目錄和存放庫。 這應該可減少代理程式用盡磁碟空間的可能性。 維護作業是在代理程式組件區設定中的專案集合或組織層級設定。

若要設定維護作業設定：

1. 選擇 [Azure DevOps]、 [組織設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 選擇 [Azure DevOps]、 [集合設定]。

   

2. 選擇 [代理程式組件區]。

   

1. 流覽至您的專案，然後選擇 [設定] (齒輪圖示) >[代理程式佇列]。

   

2. 選擇 [管理集區]。

   

選擇所需的集區，然後選擇 [ 設定 ] 來設定該代理程式組件區的維護作業設定。

重要

您必須擁有 管理組建佇列 許可權，才能設定維護作業設定。 如果您沒有看到 [ 設定 ] 索引標籤或 [ 維護歷程記錄 ] 索引標籤，則沒有該許可權，預設會授與 系統管理員 角色。 如需詳細資訊，請參閱 代理程式組件區的安全性。

設定所需的設定，然後選擇 [ 儲存]。

選取 [維護歷程記錄 ] 以查看目前代理程式組件區的維護作業歷程記錄。 您可以下載並檢閱記錄，以查看所採取的清除步驟和動作。

維護是每個代理程式組件區完成，而不是每部機器;因此，如果您在單一電腦上有多個代理程式組件區，您仍可能會遇到磁碟空間問題。

自我裝載代理程式組件區的維護作業看起來會停滯。 原因為何？

一般而言，維護作業在等候在代理程式組件區中不再執行的代理程式上執行時會「停滯」。 例如，當代理程式已離線或與代理程式通訊時發生問題時，就會發生這種情況。

已排入佇列以執行的維護作業會等候七天執行。 之後，如果未執行，系統會自動將其設定為失敗狀態。 無法變更此時間限制。

七天限制與 維護作業逾時 設定不同。 後者控制代理程式可以花費進行維護的分鐘數上限。 計時器會在作業啟動時啟動，而不是在代理程式上排入佇列時啟動。

我嘗試建立使用現有組織代理程式組件區的專案代理程式組件區，但控制項呈現灰色。為什麼？

在 [建立專案代理程式組件區] 對話方塊上，如果已由另一個專案代理程式組件區參考現有的組織代理程式組件區，您就無法使用現有的組織代理程式組件區。 每個組織代理程式組件區只能由指定專案集合內的一個專案代理程式組件區參考。

我無法選取 Microsoft 裝載的集區，而且無法將組建排入佇列。 我要如何修正此問題？

要求 Azure DevOps 組織的擁有者授與您使用集區的許可權。 請參閱 代理程式組件區的安全性。

我需要更多託管的組建資源。 我該怎麼處理？

答：Azure Pipelines 集區會為每個月提供所有 Azure DevOps 組織雲端裝載的組建代理程式和免費組建分鐘數。 如果您需要更多 Microsoft 裝載的組建資源，或需要平行執行更多作業，則可以：

• 在您所管理的基礎結構上裝載您自己的代理程式
• 購買其他平行作業