Google uses AI technology to translate content into your preferred language. AI translations can contain errors.

建立及授予服務代理角色

在 Google Cloud中，當您啟用及使用Google Cloud 服務時，系統會自動建立專案層級、資料夾層級和機構層級的服務代理。有時，系統也會自動授予這些服務代理角色，讓他們代表您建立及存取資源。

如有需要，您也可以要求 Google Cloud 在服務啟用前，為服務建立專案層級、資料夾層級和機構層級的服務代理程式。要求 Google Cloud 建立服務代理程式，可讓您在服務啟用前，將角色授予服務代理程式。如果服務代理程式尚未建立，您就無法將角色授予服務代理程式。

如果您使用下列任一策略管理允許政策，這個選項就非常實用：

類似 Terraform 的宣告式架構。 如果 Terraform 設定未包含服務代理程式的角色，套用設定時就會撤銷這些角色。在 Terraform 設定中建立服務代理程式並授予角色，可確保這些角色不會遭到撤銷。
政策即程式碼系統：將目前允許政策的副本儲存在程式碼存放區。如果您允許系統自動將角色授予服務代理程式，這些角色會顯示在實際的允許政策中，但不會顯示在允許政策的儲存副本中。 Google Cloud 如要解決這項不一致問題，您可能會誤撤銷這些角色。主動建立服務代理程式並授予角色，有助於避免程式碼存放區與實際允許政策之間發生偏移。

觸發服務代理程式建立作業後，您必須授予服務代理程式通常會自動獲得的角色。否則部分服務可能無法正常運作。這是因為應使用者要求建立的服務代理不會自動獲得角色。

事前準備

啟用 Resource Manager 和 Workload Identity API。
啟用 API 時所需的角色
如要啟用 API，您需要具備服務使用情形管理員 IAM 角色 (roles/serviceusage.serviceUsageAdmin)，其中包含 serviceusage.services.enable 權限。瞭解如何授予角色。
啟用 API
瞭解服務代理。

必要的角色

如要取得建立及授予服務代理存取權所需的權限，請要求管理員在您要建立服務代理並授予存取權的專案、資料夾和組織中，授予下列 IAM 角色：

列出可用服務及其端點：服務使用情形檢視者 (roles/serviceusage.serviceUsageViewer)
啟用服務代理： Workload Identity API 管理員 (roles/workloadidentity.admin)
授予服務代理程式專案存取權：專案 IAM 管理員 (roles/resourcemanager.projectIamAdmin)
授予服務代理程式資料夾存取權：資料夾管理員 (roles/resourcemanager.folderAdmin)
授予服務代理商專案、資料夾和機構的存取權：機構管理員 (roles/resourcemanager.organizationAdmin)

如要進一步瞭解如何授予角色，請參閱「管理專案、資料夾和組織的存取權」。

這些預先定義的角色具備建立及授予服務代理存取權所需的權限。如要查看確切的必要權限，請展開「Required permissions」(必要權限) 部分：

所需權限

如要建立及授予服務代理存取權，您必須具備下列權限：

列出可用的服務及其端點： serviceusage.services.list
啟用服務代理人： workloadidentity.serviceAgents.create
查看長時間執行的作業： workloadidentity.operations.get
授予服務代理專案存取權：
- resourcemanager.projects.getIamPolicy
- resourcemanager.projects.setIamPolicy
授予服務代理人資料夾存取權：
- resourcemanager.folders.getIamPolicy
- resourcemanager.folders.setIamPolicy
授予服務代理機構存取權：
- resourcemanager.organizations.getIamPolicy
- resourcemanager.organizations.setIamPolicy

您或許還可透過自訂角色或其他預先定義的角色取得這些權限。

找出要建立的服務代理

如要找出需要建立的服務代理程式，以及建立這些代理程式的資源，請按照下列步驟操作：

列出您使用的服務及其 API 端點。如要查看所有可用的服務及其端點，請使用下列其中一種方法：
控制台

前往 Google Cloud 控制台的「API Library」(API 程式庫) 頁面。

前往 API 程式庫

API 端點是「其他詳細資料」部分列出的「服務名稱」。
gcloud

gcloud services list 指令會列出專案的所有可用服務。

使用下方的任何指令資料之前，請先替換以下項目：
- EXPRESSION：選用。用於篩選結果的運算式。舉例來說，以下運算式會篩選名稱包含 googleapis.com 但不包含 sandbox 的所有服務：
  name ~ googleapis.com AND name !~ sandbox
  如需篩選運算式清單，請參閱 gcloud topic filters。
- LIMIT：選用。要列出的結果數上限。預設值為 unlimited。
執行下列指令：
Linux、macOS 或 Cloud Shell
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (PowerShell)
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
Windows (cmd.exe)

注意： 如果這個指令使用 ' 引號來引述內容，請將這些單引號換成雙引號。如果引用內容是巢狀結構，請使用 \" 逸出內層引號。
gcloud services list --available --filter='EXPRESSION' --limit=LIMIT
回應會列出所有可用服務的名稱和標題。API 端點是 NAME 欄位中的值。
REST

Service Usage API 的 services.list 方法會列出專案的所有可用服務。

使用任何要求資料之前，請先修改下列項目的值：
- RESOURCE_TYPE：要列出可用服務的資源類型。請使用 projects、folders 或 organizations。
- RESOURCE_ID：您要列出可用服務的 Google Cloud專案、資料夾或機構 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- PAGE_SIZE：選用。要在回應中納入的服務數量。預設值為 50，最大值為 200。如果服務數量大於頁面大小，回應會包含分頁符記，可用於擷取下一頁結果。
- NEXT_PAGE_TOKEN：選用。這個方法先前傳回的回應中包含的分頁符記。如果指定，服務清單會從上一個要求結束的位置開始。
HTTP 方法和網址：
GET https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN
請展開以下其中一個選項，以傳送要求：
curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：
curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
"https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN"
PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
-Method GET `
-Headers $headers `
-Uri "https://serviceusage.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_ID/services?pageSize=PAGE_SIZE&pageToken=NEXT_PAGE_TOKEN" | Select-Object -Expand Content
回應會包含資源的所有可用服務名稱和標題。如果可用服務數量大於頁面大小，回應也會包含分頁符記。

API 端點是 name 欄位中的值。

針對您要使用的每個 API 端點，列出需要建立該端點服務代理程式的資源：

在服務代理人參考資料頁面中，搜尋每個 API 端點，找出該端點的所有服務代理人。

部分端點可能沒有相關聯的服務代理，您可以略過為這些端點觸發服務代理建立作業。

針對每個端點的服務代理程式，請使用服務代理程式的電子郵件地址，判斷需要建立服務代理程式的位置。

服務代理電子郵件地址中的預留位置，表示您需要建立服務代理的位置：

預留位置	建立服務代理的位置
`PROJECT_NUMBER`	您要使用服務的每個專案
`FOLDER_NUMBER`	您要使用服務的每個資料夾
`ORGANIZATION_NUMBER`	您要使用服務的每個機構

針對每個端點，記錄您需要為該端點建立服務代理程式的每個專屬資源。

觸發建立服務代理

確定要建立哪些服務代理程式後，即可要求Google Cloud 建立這些代理程式。

要求 Google Cloud 建立服務代理程式時，您會提供服務和資源。接著， Google Cloud 會為該服務和資源建立所有服務代理程式。

在這個步驟中，如果您使用 gcloud CLI 或 REST API，也可以建立需要授予每個服務代理程式的角色清單。您將使用這項資訊授予服務代理程式角色。如果您使用 Terraform，則不需要手動追蹤必要角色，因為您可以透過程式輔助方式參照角色。

gcloud

使用 gcloud workload-identity service-agents generate 指令，為您在「識別要建立的服務代理」中識別的每個端點和資源建立服務代理。

每次執行指令時，請檢查回覆內容。針對回應中的每個角色，記錄應授予該角色的服務代理程式電子郵件地址。您將使用這項資訊授予服務代理程式角色。

使用下方的任何指令資料之前，請先替換以下項目：

ENDPOINT：要建立服務代理程式的 API 端點，例如 aiplatform.googleapis.com。
RESOURCE_TYPE：要建立服務代理程式的資源類型。請使用 project、folder 或 organization。
RESOURCE_ID：您要為其建立服務代理的 Google Cloud專案、資料夾或機構的數字 ID。例如：123456789012。

一次只能為一項資源建立服務代理。如要為多個資源建立服務代理程式，請針對每個資源執行一次指令。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud workload-identity service-agents generate --service="ENDPOINT" \
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (PowerShell)

gcloud workload-identity service-agents generate --service="ENDPOINT" `
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

Windows (cmd.exe)

gcloud workload-identity service-agents generate --service="ENDPOINT" ^
    --location="global" --RESOURCE_TYPE="RESOURCE_ID"

回覆會列出所有已建立的服務代理程式。針對每位服務代理人，回應會列出建立服務代理人的資源、服務代理人的電子郵件地址、服務代理人相關聯的服務，以及服務代理人的狀態。如果服務代理人通常會獲得特定角色，回應也會列出該角色。

系統不會自動將列出的角色授予服務代理。針對回應中的每個角色，記錄應授予該角色的服務代理程式電子郵件地址。您將使用這項資訊為服務代理程式授予角色。

以下是為 aiplatform.googleapis.com 建立服務代理程式的回應範例 (已截斷)。

Provisioned service agents for aiplatform.googleapis.com under projects/123456789012:

container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com
role: roles/aiplatform.serviceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----
...
----
container: projects/123456789012
principal: serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com
role: roles/aiplatform.trainingClusterServiceAgent
serviceProducer: aiplatform.googleapis.com
state: ACTIVE
----

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

使用 google_workload_identity_service_agent 資源，為您在「識別要建立的服務代理程式」中識別的每個端點和資源，觸發服務代理程式建立作業。

舉例來說，如要為預設專案建立所有 BigQuery 專案層級服務代理程式，可以在 Terraform 設定中新增下列程式碼：

data "google_project" "default" {
}

# Create all project-level bigquery.googleapis.com service agents
resource "google_workload_identity_service_agent" "primary" {
  parent = "projects/${data.google_project.default.number}/locations/global/serviceProducers/bigquery.googleapis.com"
}

REST

針對需要建立服務代理程式的每個端點，請執行下列操作：

為您在「找出要建立的服務代理程式」中識別的每個資源建立服務代理程式：

使用任何要求資料之前，請先修改下列項目的值：

RESOURCE_TYPE：要為其建立服務代理程式的資源類型。請使用 projects、folders 或 organizations。
RESOURCE_NUMERIC_ID：您要建立服務代理的 Google Cloud 專案、資料夾或機構的數字 ID。例如：123456789012。

一次只能為一項資源建立服務代理。如要為多個資源建立服務代理程式，請分別為每個資源傳送要求。
ENDPOINT：要建立服務代理程式的 API 端點，例如 aiplatform.googleapis.com。

HTTP 方法和網址：

POST https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d "" \
     "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/RESOURCE_TYPE/RESOURCE_NUMERIC_ID/locations/global/serviceProducers/ENDPOINT:generateServiceAgents" | Select-Object -Expand Content

回應包含 Operation，指出要求的狀態。例如：

{
  "name": "projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T21:15:41.367155118Z",
    "target": "projects/123456789012/locations/global/serviceProducers/bigquery.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

從完成的作業取得回應。針對回應中的每個角色，記錄應授予該角色的服務代理程式電子郵件地址。您將使用這項資訊授予服務代理程式角色。

使用任何要求資料之前，請先修改下列項目的值：

OPERATION_NAME：generateServiceAgents 作業的名稱。從 serviceProducers.generateServiceAgents 回應的 name 欄位複製這個值。例如：projects/123456789012/locations/global/operations/operation-1775250941060-64e94d1baa76d-1aa958f3-07b2ea9c
PROJECT_ID：您的 Google Cloud 專案 ID。專案 ID 為英數字串，例如 my-project。

HTTP 方法和網址：

GET https://workloadidentity.googleapis.com/v1/OPERATION_NAME

請展開以下其中一個選項，以傳送要求：

curl (Linux、macOS 或 Cloud Shell)

執行下列指令：

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://workloadidentity.googleapis.com/v1/OPERATION_NAME"

PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

執行下列指令：

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://workloadidentity.googleapis.com/v1/OPERATION_NAME" | Select-Object -Expand Content

APIs Explorer (瀏覽器)

開啟方法參考頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。完成任何必填欄位，然後按一下「執行」。

執行中的作業會傳回類似以下的回應：

{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": false
}

完成的作業會傳回回應，其中包含已建立的服務代理程式清單。針對每位服務代理人，回覆會列出建立服務代理人的資源、服務代理人的電子郵件地址、服務代理人相關聯的服務，以及服務代理人的狀態。如果服務代理程式通常會獲得特定角色，回應也會列出該角色。

以下是為 aiplatform.googleapis.com 建立服務代理程式的回應範例 (已截斷)。

{
  "name": "projects/123456789012/locations/global/operations/operation-1775258415970-64e968f44b91a-28fcf2f5-38367cfe",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.OperationMetadata",
    "createTime": "2026-04-03T23:20:15.982631253Z",
    "endTime": "2026-04-03T23:20:17.315225515Z",
    "target": "projects/123456789012/locations/global/serviceProducers/aiplatform.googleapis.com",
    "verb": "passthroughLro",
    "requestedCancellation": false,
    "apiVersion": "v1"
  },
  "done": true,
  "response": {
    "@type": "type.googleapis.com/google.cloud.workloadidentity.v1.GenerateServiceAgentsResponse",
    "serviceAgents": [
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-aiplatform.iam.gserviceaccount.com",
        "role": "roles/aiplatform.serviceAgent",
        "state": "ACTIVE"
      },
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-ri-aiplatform.iam.gserviceaccount.com",
        "state": "ACTIVE"
      },
      ...
      {
        "container": "projects/123456789012",
        "serviceProducer": "aiplatform.googleapis.com",
        "principal": "serviceAccount:service-123456789012@gcp-sa-vertex-vtc.iam.gserviceaccount.com",
        "role": "roles/aiplatform.trainingClusterServiceAgent",
        "state": "ACTIVE"
      }
    ]
  }
}

將角色授予服務代理人

Google Cloud 為專案、資料夾和機構建立必要的服務代理程式後，您可以使用服務代理程式的電子郵件地址授予角色。

如果您要求 Google Cloud 建立服務代理，則必須授予這些服務代理通常會自動獲得的角色。否則部分服務可能無法正常運作。這是因為應使用者要求建立的服務代理程式不會自動獲得角色。

控制台

使用您在「觸發服務代理程式建立作業」中建立的角色和服務代理程式清單，找出需要授予角色的服務代理程式。針對每個需要角色的服務代理程式，請執行下列操作：

前往 Google Cloud 控制台的「IAM」(身分與存取權管理) 頁面。

前往 IAM
選取您為服務代理程式建立的專案、資料夾或機構。
按一下「授予存取權」，然後輸入服務代理的電子郵件地址。
按一下「選取角色」，然後輸入角色或權限名稱，篩選要授予的角色。為遵循最小權限原則，請選擇僅含主體所需權限的角色。
按一下 [儲存]。服務代理程式會取得資源的角色。

gcloud

使用您在「觸發服務代理程式建立作業」中建立的角色和服務代理程式清單，找出需要授予角色的服務代理程式。針對每個需要角色的服務代理程式，使用 add-iam-policy-binding 指令將角色授予服務代理程式。

使用下方的任何指令資料之前，請先替換以下項目：

RESOURCE_TYPE：要管理存取權的資源類型。請使用 projects、resource-manager folders 或 organizations。
RESOURCE_ID：您的 Google Cloud 專案、資料夾或組織 ID。專案 ID 為英數字元，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
PRINCIPAL：要授予存取權的服務代理人電子郵件地址，並加上 serviceAccount: 前置字元。例如：serviceAccount:service-0123456789012@gcp-sa-aiplatform-cc.iam.gserviceaccount.com。
ROLE_NAME：您要授予服務代理的角色名稱。

執行下列指令：

Linux、macOS 或 Cloud Shell

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID \
    --member=PRINCIPAL --role=ROLE_NAME \
    --condition=CONDITION

Windows (PowerShell)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID `
    --member=PRINCIPAL --role=ROLE_NAME `
    --condition=CONDITION

Windows (cmd.exe)

gcloud RESOURCE_TYPE add-iam-policy-binding RESOURCE_ID ^
    --member=PRINCIPAL --role=ROLE_NAME ^
    --condition=CONDITION

回應會包含更新後的 IAM 允許政策。

Terraform

如要瞭解如何套用或移除 Terraform 設定，請參閱「基本 Terraform 指令」。詳情請參閱 Terraform 供應商參考文件。

如要將角色授予服務專員，請按照下列步驟操作：

針對每個 google_workload_identity_service_agent 資源，授予與服務代理相關聯的任何角色。

舉例來說，如要將角色授予 google_workload_identity_service_agent.primary 資源的所有服務代理程式，您可以將下列程式碼新增至 Terraform 設定：

# Grant roles to BigQuery service agents for project
resource "google_project_iam_member" "service_agents" {
  for_each = {
    for i, agent in google_workload_identity_service_agent.primary.service_agents :
    i => agent if try(agent.role, "") != ""
  }
  project = data.google_project.default.project_id
  role    = each.value.role
  member  = each.value.principal
}

針對您在本頁「觸發服務代理程式建立作業」一節中新增的 google_workload_identity_service_agent 資源，執行目標 terraform apply 指令。
舉例來說，如果您新增名為 google_workload_identity_service_agent.primary 的資源，請執行下列指令：
```
terraform apply target="google_workload_identity_service_agent.primary"
```
執行這項指令可確保 google_project_iam_member 資源能參照服務代理程式資源，不會發生 Known After Apply 錯誤。
針對 Terraform 設定執行 terraform plan 指令。這個指令會顯示將角色授予服務代理的執行計畫。如果執行計畫沒問題，請執行 terraform apply 來套用計畫。

REST

使用您在「觸發服務代理程式建立作業」中建立的角色和服務代理程式清單，找出需要授予角色的服務代理程式。如要將角色授予服務代理程式，請使用讀取 - 修改 - 寫入模式更新資源的允許政策：

呼叫 getIamPolicy 讀取目前的允許政策。

使用任何要求資料之前，請先修改下列項目的值：
- API_VERSION：要使用的 API 版本。如果是專案和機構，請使用 v1。如果是資料夾，請使用 v2。
- RESOURCE_TYPE：要管理政策的資源類型。請使用 projects、folders 或 organizations 值。
- RESOURCE_ID：您的 Google Cloud專案、機構或資料夾 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- POLICY_VERSION：要傳回的政策版本。要求應指定最新政策版本，也就是政策版本 3。詳情請參閱在取得政策時指定政策版本。
HTTP 方法和網址：
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy
```
JSON 要求主體：
```
{
  "options": {
    "requestedPolicyVersion": POLICY_VERSION
  }
}
```
請展開以下其中一個選項，以傳送要求：
curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy"
```
PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:getIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「執行」。

回應會包含資源的允許政策。例如：
```
{
  "version": 1,
  "etag": "BwWKmjvelug=",
  "bindings": [
    {
      "role": "roles/owner",
      "members": [
        "user:my-user@example.com"
      ]
    }
  ]
}
```
為要授予角色的每個服務代理建立角色繫結，授予服務代理必要角色。舉例來說，下列角色繫結會將 Vertex AI 自訂程式碼服務代理人角色 (roles/aiplatform.customCodeServiceAgent) 授予 AI Platform 自訂程式碼服務代理人：
```
  {
    "role": "roles/aiplatform.customCodeServiceAgent",
    "members": [
      "serviceAccount:service-PROJECT_NUMBER@gcp-sa-aiplatform-cc.iam.gserviceaccount.com",
    ]
  }
```
如果允許政策已具備必要角色的角色繫結，請將服務代理新增至該角色繫結的 members 清單。
呼叫 setIamPolicy，寫入更新後的允許政策。

使用任何要求資料之前，請先修改下列項目的值：
- API_VERSION：要使用的 API 版本。如果是專案和機構，請使用 v1。如果是資料夾，請使用 v2。
- RESOURCE_TYPE：要管理政策的資源類型。請使用 projects、folders 或 organizations 值。
- RESOURCE_ID：您的 Google Cloud專案、機構或資料夾 ID。專案 ID 為英數字串，例如 my-project。資料夾和機構 ID 為數字，例如 123456789012。
- POLICY：您要設定的政策的 JSON 表示法。如要進一步瞭解政策格式，請參閱政策參考資料。
HTTP 方法和網址：
```
POST https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy
```
JSON 要求主體：
```
{
  "policy": POLICY
}
```
請展開以下其中一個選項，以傳送要求：
curl (Linux、macOS 或 Cloud Shell)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI，或已使用 Cloud Shell 自動登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
```
curl -X POST \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json; charset=utf-8" \
     -d @request.json \
     "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy"
```
PowerShell (Windows)

注意：下列指令假設您已執行 gcloud init 或 gcloud auth login，透過使用者帳戶登入 gcloud CLI。您可以執行 gcloud auth list，查看目前使用的帳戶。

將要求主體儲存在名為 request.json 的檔案中，然後執行下列指令：
```
$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method POST `
    -Headers $headers `
    -ContentType: "application/json; charset=utf-8" `
    -InFile request.json `
    -Uri "https://cloudresourcemanager.googleapis.com/API_VERSION/RESOURCE_TYPE/RESOURCE_ID:setIamPolicy" | Select-Object -Expand Content
```
APIs Explorer (瀏覽器)

複製要求內文並開啟方法參考資料頁面。系統會在頁面右側開啟 APIs Explorer 面板。您可以使用這項工具來傳送要求。將要求內文貼到這項工具中，並填妥其他必填欄位，然後按一下「執行」。

回應會包含更新後的允許政策。

注意：如果您將政策視為程式碼並儲存在版本控制系統中，請儲存傳回的政策，而非您在要求中傳送的政策。

後續步驟

查看所有服務代理的清單。
瞭解如何將角色授予主體。
瞭解如何建立使用者自行管理的服務帳戶，做為工作負載的身分。
進一步瞭解在Google Cloud上使用 Terraform 的最佳做法。
探索所有 Google Cloud Terraform 範例。

建立及授予服務代理角色 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

事前準備

必要的角色

所需權限

找出要建立的服務代理

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

觸發建立服務代理

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

APIs Explorer (瀏覽器)

將角色授予服務代理人

控制台

gcloud

Linux、macOS 或 Cloud Shell

Windows (PowerShell)

Windows (cmd.exe)

Terraform

REST

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

APIs Explorer (瀏覽器)

curl (Linux、macOS 或 Cloud Shell)

PowerShell (Windows)

APIs Explorer (瀏覽器)

後續步驟

建立及授予服務代理角色