管理代理程式集區

代理程式集區是一組代理程式，這些代理程式使用相同的設定，且具有來源和目的地的統一存取權和可見度。代理程式集區也能控管傳輸頻寬上限。

所有代理程式都必須屬於代理程式集區。

本指南說明如何使用代理程式集區。

事前準備

您必須具備專案的正確權限，才能使用代理程式集區。 詳情請參閱「使用 IAM 控管存取權」。

你可以查看目前的權限。

如要使用 gcloud 指令，請安裝 gcloud 指令列工具。

建立代理程式集區

請勿在代理程式集區名稱或代理程式 ID 前置字元中，加入個人識別資訊 (PII) 或安全性資料等私密資訊。資源名稱可能會傳播至其他 Google Cloud 資源的名稱，並可能向專案外部的 Google 內部系統公開。

如要建立代理程式集區，請按照下列指示操作：

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent pools」頁面。

    前往代理程式集區

    系統會顯示「代理程式集區」頁面，列出您現有的代理程式集區。

  2. 按一下「建立其他集區」。

  3. 為集區命名，並視需要提供說明。

  4. 您可以選擇設定頻寬限制，並套用至整個集區。系統會將指定的 MB/s 頻寬分配給集區中的所有代理程式。詳情請參閱「管理網路頻寬」。

  5. 點選「建立」。

REST API

使用 projects.agentPools.create：

POST https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools?agent_pool_id=AGENT_POOL_ID

其中：

  • PROJECT_ID：您要在其中建立代理程式集區的專案 ID。
  • AGENT_POOL_ID：要建立的代理程式集區 ID。

如果代理程式集停滯在 Creating 狀態超過 30 分鐘，建議刪除並重新建立代理程式集。

如果代理程式集區處於 Creating 狀態，從專案撤銷必要的 Storage 移轉服務權限，會導致服務行為異常。

gcloud CLI

如要使用 gcloud 指令列工具建立代理程式集區，請執行 gcloud transfer agent-pools create。

gcloud transfer agent-pools create AGENT_POOL

可用的選項如下：

  • AGENT_POOL 是這個集區的專屬永久 ID。

  • --no-async 會封鎖終端機中的其他工作，直到集區建立完成為止。如果未納入，集區建立作業會以非同步方式執行。

  • --bandwidth-limit 定義這個集區的代理程式可以使用多少頻寬 (以 MB/s 為單位)。頻寬限制會套用至集區中的所有代理程式，可防止集區的轉移工作負載導致共用頻寬的其他作業發生中斷。舉例來說，輸入「50」即可將頻寬上限設為 50 MB/s。如未指定這個旗標，這個集區的代理程式將使用所有可用頻寬。

  • --display-name 是可修改的名稱，方便您識別這個集區。您可以加入可能不適合用於集區專屬完整資源名稱的詳細資料。

將代理程式指派給集區

新的代理程式集區是空的，必須指派代理程式。代理程式只能在建立時指派給代理程式集區。

如果未指定代理程式集區，系統會將代理程式指派給 transfer_service_default 集區。

如要建立代理程式並指派給集區，請按照下列步驟操作：

Google Cloud 控制台

  1. 在「代理程式集區」頁面中，選取要指派代理程式的集區。

  2. 按一下「安裝代理程式」。系統隨即會顯示代理程式安裝指南。

  3. 按照操作說明，在這個代理程式集區中建立代理程式。

gcloud CLI

如要使用 gcloud 指令列工具建立代理程式並指派給集區，請執行 gcloud transfer agents install。代理程式必須安裝在具有檔案系統根目錄存取權的機器上。

gcloud transfer agents install --pool=AGENT_POOL

如要安裝代理程式以搭配 S3 相容來源使用，請以環境變數的形式提供存取憑證，做為 AWS_ACCESS_KEY_ID 和 AWS_SECRET_ACCESS_KEY 的值，或將憑證儲存在系統設定檔案中做為預設憑證。

export AWS_ACCESS_KEY_ID=ID
export AWS_SECRET_ACCESS_KEY=SECRET
gcloud transfer agents install --pool=AGENT_POOL

詳情請參閱「管理轉移代理人」。

如需其他選項，請參閱「進階代理程式選項」。

如要管理代理程式，請參閱「管理轉接專員」。

將代理程式集區指派給工作

建立代理程式集區後，即可在建立或更新工作時，將集區指派給工作。

更新代理程式集區

您可以更新代理程式集區的顯示名稱和頻寬限制。

如要更新代理程式集區：

Google Cloud 控制台

前往 Google Cloud 控制台的「Agent pools」頁面。

前往代理程式集區

你可以編輯下列項目：

  • 代理程式集區的顯示名稱：按一下目前「代理程式集區」名稱旁的「編輯」。

  • 代理程式集區的頻寬限制：按一下「設定頻寬限制」，然後在「設定頻寬限制」對話方塊中輸入新的頻寬限制。按一下「設定限制」，套用新的頻寬限制。集區中的所有代理程式都會共用頻寬。

REST API

如要更新代理程式集區，請使用 projects.agentPools.patch，並提供要更新的欄位欄位遮罩。您可以更新下列代理程式集區欄位：

舉例來說，如要將 displayName 更新為 my-transfer，請提供欄位遮罩 "displayName,my-transfer"。

以下是更新顯示名稱的修補要求範例：

PATCH https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL:"displayName,NEW_DISPLAY_NAME"

其中：

  • PROJECT_ID：您要更新代理程式集區的專案 ID。
  • AGENT_POOL：要更新的代理程式集區名稱。
  • NEW_DISPLAY_NAME：這個代理程式集區的新顯示名稱。

以下是更新頻寬限制的修補要求範例：

PATCH https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL:"bandwidthLimit,NEW_LIMIT"

其中：

  • PROJECT_ID：您要更新代理程式集區的專案 ID。
  • AGENT_POOL：要更新的代理程式集區 ID。
  • NEW_LIMIT：這個代理程式集區的新頻寬限制。

gcloud CLI

如要使用 gcloud 指令列工具更新代理程式集區，請執行 gcloud transfer agent-pools update。

gcloud transfer agent-pools update AGENT_POOL \
  [--bandwidth-limit=NEW_BANDWIDTH_LIMIT] [--clear-bandwidth-limit] \
  [--clear-display-name] [--display-name=NEW_DISPLAY_NAME]

必須提供以下引數：

  • AGENT_POOL 是這個集區的專屬永久 ID。 AGENT_POOL 會識別要更新的代理程式集區，且本身無法更新。

這個指令可以指定下列標記：

  • --bandwidth-limit 可以更新，也可以指定 --clear-bandwidth-limit 移除。如要進一步瞭解頻寬限制，請參閱「建立代理程式集區」。

  • --display-name 可以更新，也可以使用 --clear-display-name 旗標刪除。

刪除代理程式集區

如果代理程式集區沒有任何使用中的代理程式和工作執行作業，即可刪除。

如要刪除代理程式集區，請按照下列步驟操作：

Google Cloud 控制台

  1. 前往 Google Cloud 控制台的「Agent pools」頁面。

    前往代理程式集區

  2. 按一下「刪除」圖示 。閱讀彈出式視窗中的內容，然後按一下「Delete」(刪除) 確認操作。

    如果刪除按鈕未啟用，您必須停止與這個集區相關聯的所有代理程式和工作。

REST API

使用 projects.agentPools.delete：

DELETE https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

其中：

  • PROJECT_ID：您要從中刪除代理程式集區的專案 ID。
  • AGENT_POOL：代理程式集區名稱。

gcloud CLI

如要使用 gcloud 指令列工具刪除代理程式集區，請執行 gcloud transfer agent-pools delete。

gcloud transfer agent-pools delete AGENT_POOL

必須提供以下引數：

  • AGENT_POOL 是這個集區的專屬永久 ID。

如要刪除集區，必須先停止集區中的所有代理程式、停用集區的工作，且集區不得有進行中的轉移作業。

如要查看與集區相關聯的所有工作，請在 Google Cloud 控制台中選取集區，然後按一下「Transfer jobs」(轉移工作) 分頁標籤。

取得代理程式集區

如要取得代理程式集區：

Google Cloud 控制台

前往 Google Cloud 控制台的「Agent pools」頁面。

前往代理程式集區

這個頁面會顯示與專案相關聯的所有代理程式集區清單，以及每個代理程式集區的下列資訊：

  • 代理程式集區名稱
  • 連線狀態
  • 已連線的代理程式數量
  • 頻寬限制 (如有設定)
  • 相關聯的轉移工作數量
  • 代理程式集區的顯示名稱

如要查看特定代理程式集區，請按一下代理程式集區的「名稱」。

您可以在代理程式集區的資訊頁面執行下列動作：

  • 安裝代理程式：顯示安裝轉移代理程式的操作說明。
  • 停止代理程式：在表格中選取代理程式，然後按一下「停止代理程式」。
  • 列出轉移工作：按一下「轉移工作」，即可顯示這個集區中的代理程式所連結的轉移工作。

REST API

使用 projects.agentPools.get：

GET https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools/AGENT_POOL

其中：

  • PROJECT_ID：您要取得代理程式集區的專案 ID。
  • AGENT_POOL：要擷取的代理程式集區。

gcloud CLI

如要使用 gcloud 指令列工具擷取代理程式集區，請執行 gcloud transfer agent-pools describe。

gcloud transfer agent-pools describe AGENT_POOL

必須提供以下引數：

  • AGENT_POOL 是這個集區的專屬永久 ID。

列出代理程式集區

如要列出代理程式集區，請按照下列步驟操作：

Google Cloud 控制台

前往 Google Cloud 控制台的「Agent pools」頁面。

前往代理程式集區

系統會顯示所有代理程式集區。

REST API

使用 projects.agentPools.list：

GET https://storagetransfer.googleapis.com/v1/projects/PROJECT_ID/agentPools

其中：

  • PROJECT_ID：要列出代理程式集區的專案 ID。

gcloud CLI

如要使用 gcloud 指令列工具列出代理程式集區，請執行 gcloud transfer agent-pools list。

gcloud transfer agent-pools list \
  [--limit=LIMIT] \
  [--names=[NAMES,...]] \
  [--page-size=PAGE_SIZE]

這個指令可以指定下列標記：

  • --limit 定義要傳回的代理程式集區數量上限。

  • --names 會指定要列出的代理程式集區名稱。如有多個名稱，請以半形逗號分隔，例如 --names=foo,bar。如未指定，系統會列出目前專案中的所有代理程式集區。

  • --page-size 會定義這個指令的批次處理行為。根據預設，list 指令會將回應分批處理，每批 256 個項目，並自動擷取下一批，直到列出所有項目或達到 limit 為止。

這項指令會傳回相符的代理程式集區清單，以及設定詳細資料。以下範例顯示範例回應。

name: projects/my-project-123/agentPools/my-first-pool
state: CREATED
---
bandwidthLimit:
  limitMbps: '120'
displayName: Source A to destination Z.
name: projects/my-project-123/agentPools/a2z-pool
state: CREATED