本頁面由 Cloud Translation API 翻譯而成。

Package google.iam.v1

索引

IAMPolicy (介面)
Binding (訊息)
GetIamPolicyRequest (訊息)
GetPolicyOptions (訊息)
Policy (訊息)
SetIamPolicyRequest (訊息)
TestIamPermissionsRequest (訊息)
TestIamPermissionsResponse (訊息)

IAMPolicy

API 總覽

管理身分與存取權管理 (IAM) 政策。

任何提供存取權控管功能的 API 實作項目都會實作 google.iam.v1.IAMPolicy 介面。

資料模型

當主體 (使用者或服務帳戶) 對服務公開的資源採取某些動作時，系統就會套用存取權控制機制。資源會以類似 URI 的名稱識別，是存取控制規範的單位。服務實作可以選擇存取權控制的精細程度，以及資源支援的權限。舉例來說，某個資料庫服務可能只允許在資料表層級指定存取權控管，而另一個服務則可能允許在資料欄層級指定存取權控管。

政策結構

請參閱 google.iam.v1.Policy

這項 API 並非 CRUD 樣式，因為存取權控管政策會與其所附加的資源一併建立及刪除。

GetIamPolicy

GetIamPolicy
`rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)` 取得資源的存取權控管政策。如果該資源存在且未設定政策，則會傳回空的政策。授權範圍需要下列 OAuth 範圍： `https://www.googleapis.com/auth/cloud-platform` 詳情請參閱驗證總覽一文。

rpc GetIamPolicy(GetIamPolicyRequest) returns (Policy)

取得資源的存取權控管政策。如果該資源存在且未設定政策，則會傳回空的政策。

授權範圍

需要下列 OAuth 範圍：

https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

SetIamPolicy

SetIamPolicy
`rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)` 設定指定資源的存取權控管政策，取代任何現有的政策。可能會傳回 `NOT_FOUND`、`INVALID_ARGUMENT` 和 `PERMISSION_DENIED` 錯誤。授權範圍需要下列 OAuth 範圍： `https://www.googleapis.com/auth/cloud-platform` 詳情請參閱驗證總覽一文。

rpc SetIamPolicy(SetIamPolicyRequest) returns (Policy)

設定指定資源的存取權控管政策，取代任何現有的政策。

可能會傳回 NOT_FOUND、INVALID_ARGUMENT 和 PERMISSION_DENIED 錯誤。

授權範圍

需要下列 OAuth 範圍：

https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

TestIamPermissions

TestIamPermissions
`rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)` 傳回呼叫者對指定資源所擁有的權限。如果資源不存在，則會傳回空白的權限組合，而非 `NOT_FOUND` 錯誤。附註：這項作業是設計用於建構權限感知 UI 和指令列工具，而不是用於授權檢查。這項作業可能會在沒有警告的情況下產生「失敗開放」。授權範圍需要下列 OAuth 範圍： `https://www.googleapis.com/auth/cloud-platform` 詳情請參閱驗證總覽一文。

rpc TestIamPermissions(TestIamPermissionsRequest) returns (TestIamPermissionsResponse)

傳回呼叫者對指定資源所擁有的權限。如果資源不存在，則會傳回空白的權限組合，而非 NOT_FOUND 錯誤。

附註：這項作業是設計用於建構權限感知 UI 和指令列工具，而不是用於授權檢查。這項作業可能會在沒有警告的情況下產生「失敗開放」。

授權範圍

需要下列 OAuth 範圍：

https://www.googleapis.com/auth/cloud-platform

詳情請參閱驗證總覽一文。

繫結

將 members (或主要實體) 與 role 建立關聯。

欄位

欄位
`role`	`string` 指派給 `members` 清單或主體的角色。例如 `roles/viewer`、`roles/editor` 或 `roles/owner`。
`members[]`	`string` 指定要求 Google Cloud 資源存取權的主體。`members` 的值可能如下： `allUsers`：這種特殊的身分識別代表網際網路上的所有使用者，無論該使用者是否有 Google 帳戶。 `allAuthenticatedUsers`：這種特殊的身分識別代表任何透過 Google 帳戶或服務帳戶進行驗證的使用者。不包含透過身分聯盟機制取得的第三方身分提供者 (IdP) 所提供的身分。 `user:{emailid}`：代表特定 Google 帳戶的電子郵件地址，例如：`alice@example.com`。 `serviceAccount:{emailid}`：代表 Google 服務帳戶的電子郵件地址。例如：`my-other-app@appspot.gserviceaccount.com`。 `serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]`：Kubernetes 服務帳戶的 ID。例如：`my-project.svc.id.goog[my-namespace/my-kubernetes-sa]`。 `group:{emailid}`：代表 Google 群組的電子郵件地址。例如：`admins@example.com`。 `domain:{domain}`：代表該網域所有使用者的 G Suite 網域 (主要)，例如 `google.com` 或 `example.com`。 `deleted:user:{emailid}?uid={uniqueid}`：代表最近刪除的使用者電子郵件地址 (加上專屬 ID)。例如：`alice@example.com?uid=123456789012345678901`。如果使用者已復原，這個值會還原為 `user:{emailid}`，且復原的使用者會保留綁定中的角色。 `deleted:serviceAccount:{emailid}?uid={uniqueid}`：代表最近刪除的服務帳戶的電子郵件地址 (加上專屬 ID)。例如 `my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901`。如果服務帳戶未刪除，這個值會還原為 `serviceAccount:{emailid}`，且未刪除的服務帳戶會保留繫結中的角色。 `deleted:group:{emailid}?uid={uniqueid}`：代表最近已刪除的 Google 群組的電子郵件地址 (加上專屬 ID)。例如，`admins@example.com?uid=123456789012345678901`。如果群組已復原，這個值會還原為 `group:{emailid}`，且復原的群組會保留繫結中的角色。
`condition`	`Expr` 與此繫結相關聯的條件。如果條件評估為 `true`，則此繫結會套用至目前要求。如果條件評估為 `false`，則此繫結不適用於目前要求。不過，不同的角色繫結可能會為此繫結中的一或多個主體授予相同的角色。如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

role

string

指派給 members 清單或主體的角色。例如 roles/viewer、roles/editor 或 roles/owner。

members[]

string

指定要求 Google Cloud 資源存取權的主體。members 的值可能如下：

allUsers：這種特殊的身分識別代表網際網路上的所有使用者，無論該使用者是否有 Google 帳戶。
allAuthenticatedUsers：這種特殊的身分識別代表任何透過 Google 帳戶或服務帳戶進行驗證的使用者。不包含透過身分聯盟機制取得的第三方身分提供者 (IdP) 所提供的身分。
user:{emailid}：代表特定 Google 帳戶的電子郵件地址，例如：alice@example.com。

serviceAccount:{emailid}：代表 Google 服務帳戶的電子郵件地址。例如：my-other-app@appspot.gserviceaccount.com。
serviceAccount:{projectid}.svc.id.goog[{namespace}/{kubernetes-sa}]：Kubernetes 服務帳戶的 ID。例如：my-project.svc.id.goog[my-namespace/my-kubernetes-sa]。
group:{emailid}：代表 Google 群組的電子郵件地址。例如：admins@example.com。

domain:{domain}：代表該網域所有使用者的 G Suite 網域 (主要)，例如 google.com 或 example.com。

deleted:user:{emailid}?uid={uniqueid}：代表最近刪除的使用者電子郵件地址 (加上專屬 ID)。例如：alice@example.com?uid=123456789012345678901。如果使用者已復原，這個值會還原為 user:{emailid}，且復原的使用者會保留綁定中的角色。
deleted:serviceAccount:{emailid}?uid={uniqueid}：代表最近刪除的服務帳戶的電子郵件地址 (加上專屬 ID)。例如 my-other-app@appspot.gserviceaccount.com?uid=123456789012345678901。如果服務帳戶未刪除，這個值會還原為 serviceAccount:{emailid}，且未刪除的服務帳戶會保留繫結中的角色。
deleted:group:{emailid}?uid={uniqueid}：代表最近已刪除的 Google 群組的電子郵件地址 (加上專屬 ID)。例如，admins@example.com?uid=123456789012345678901。如果群組已復原，這個值會還原為 group:{emailid}，且復原的群組會保留繫結中的角色。

condition

Expr

與此繫結相關聯的條件。

如果條件評估為 true，則此繫結會套用至目前要求。

如果條件評估為 false，則此繫結不適用於目前要求。不過，不同的角色繫結可能會為此繫結中的一或多個主體授予相同的角色。

如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

GetIamPolicyRequest

GetIamPolicy 方法的要求訊息。

欄位

欄位
`resource`	`string` 必要：要求政策的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。
`options`	`GetPolicyOptions` 選用：用來指定 `GetIamPolicy` 相關選項的 `GetPolicyOptions` 物件。

resource

string

必要：要求政策的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。

options

GetPolicyOptions

選用：用來指定 GetIamPolicy 相關選項的 GetPolicyOptions 物件。

GetPolicyOptions

封裝提供給 GetIamPolicy 的設定。

欄位

欄位
`requested_policy_version`	`int32` (非必要) 用於格式化政策的最高政策版本。有效值為 0、1 和 3。系統會拒絕指定無效值的要求。如要要求含有任何條件式角色繫結的政策，請務必指定第 3 版。沒有條件式角色繫結的政策可以指定任何有效值，也可以不設定該欄位。回應中的政策可能會使用您指定的政策版本，也可能會使用較舊的政策版本。舉例來說，如果您指定版本 3，但政策中沒有條件式角色繫結，回應就會使用版本 1。如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

requested_policy_version

int32

(非必要) 用於格式化政策的最高政策版本。

有效值為 0、1 和 3。系統會拒絕指定無效值的要求。

如要要求含有任何條件式角色繫結的政策，請務必指定第 3 版。沒有條件式角色繫結的政策可以指定任何有效值，也可以不設定該欄位。

回應中的政策可能會使用您指定的政策版本，也可能會使用較舊的政策版本。舉例來說，如果您指定版本 3，但政策中沒有條件式角色繫結，回應就會使用版本 1。

如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

政策

身分與存取權管理 (IAM) 政策，可指定 Google Cloud 資源的存取權控管。

Policy 是 bindings 的集合。binding 會將一或多個 members (或主體) 繫結至單一 role。主體可以是使用者帳戶、服務帳戶、Google 群組和網域 (例如 G Suite)。role 是具名權限清單，每個 role 可以是 IAM 預先定義的角色，或使用者建立的自訂角色。

對於某些類型的 Google Cloud 資源，binding 也可以指定 condition，這是邏輯運算式，只有在運算式評估為 true 時，才能存取資源。條件可以根據要求或資源的屬性 (或兩者) 新增限制。如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

JSON 範例：

    {
      "bindings": [
        {
          "role": "roles/resourcemanager.organizationAdmin",
          "members": [
            "user:mike@example.com",
            "group:admins@example.com",
            "domain:google.com",
            "serviceAccount:my-project-id@appspot.gserviceaccount.com"
          ]
        },
        {
          "role": "roles/resourcemanager.organizationViewer",
          "members": [
            "user:eve@example.com"
          ],
          "condition": {
            "title": "expirable access",
            "description": "Does not grant access after Sep 2020",
            "expression": "request.time < timestamp('2020-10-01T00:00:00.000Z')",
          }
        }
      ],
      "etag": "BwWWja0YfJA=",
      "version": 3
    }

YAML 範例：

    bindings:
    - members:
      - user:mike@example.com
      - group:admins@example.com
      - domain:google.com
      - serviceAccount:my-project-id@appspot.gserviceaccount.com
      role: roles/resourcemanager.organizationAdmin
    - members:
      - user:eve@example.com
      role: roles/resourcemanager.organizationViewer
      condition:
        title: expirable access
        description: Does not grant access after Sep 2020
        expression: request.time < timestamp('2020-10-01T00:00:00.000Z')
    etag: BwWWja0YfJA=
    version: 3

如需 IAM 及其功能的說明，請參閱 IAM 說明文件。

欄位

欄位
`version`	`int32` 指定政策的格式。有效值為 `0`、`1` 和 `3`。系統會拒絕指定無效值的要求。任何影響條件角色繫結的作業都必須指定 `3` 版本。這項規定適用於下列作業：取得包含條件式角色繫結的政策將條件角色繫結新增至政策變更政策中的條件式角色繫結從包含條件的政策中移除任何角色繫結 (不論是否有條件) 重要事項：如果您使用 IAM 條件，每次呼叫 `setIamPolicy` 時都必須加入 `etag` 欄位。如果您省略這個欄位，IAM 就會允許您使用版本 `1` 政策覆寫版本 `3` 政策，而版本 `3` 政策中的所有條件都會遺失。如果政策不包含任何條件，對該政策執行的作業可以指定任何有效版本，也可以不指定欄位。如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。
`bindings[]`	`Binding` 將 `members` 或主體清單與 `role` 建立關聯。您可以視需要指定 `condition`，以決定套用 `bindings` 的方式和時機。每個 `bindings` 都必須包含至少一個主要元素。 `Policy` 中的 `bindings` 最多可參照 1,500 個主體，其中最多 250 個主體可為 Google 群組。每個主體都會計入這些限制。舉例來說，如果 `bindings` 將 50 個不同角色授予 `user:alice@example.com`，但沒有授予其他主體，您就可以在 `Policy` 中將其他 1,450 個主體新增至 `bindings`。
`etag`	`bytes` `etag` 用於開放式並行控制，有助防止政策在同時更新時相互覆寫。強烈建議系統在讀取-修改-寫入週期中使用 `etag` 執行政策更新，以避免發生競爭狀況：`getIamPolicy` 的回應會傳回 `etag`，系統應將該 etag 放入 `setIamPolicy` 的要求中，確保變更會套用至相同版本的政策。重要事項：如果您使用 IAM 條件，每次呼叫 `setIamPolicy` 時都必須加入 `etag` 欄位。如果您省略這個欄位，IAM 就會允許您使用版本 `1` 政策覆寫版本 `3` 政策，而版本 `3` 政策中的所有條件都會遺失。

version

int32

指定政策的格式。

有效值為 0、1 和 3。系統會拒絕指定無效值的要求。

任何影響條件角色繫結的作業都必須指定 3 版本。這項規定適用於下列作業：

取得包含條件式角色繫結的政策
將條件角色繫結新增至政策
變更政策中的條件式角色繫結
從包含條件的政策中移除任何角色繫結 (不論是否有條件)

重要事項：如果您使用 IAM 條件，每次呼叫 setIamPolicy 時都必須加入 etag 欄位。如果您省略這個欄位，IAM 就會允許您使用版本 1 政策覆寫版本 3 政策，而版本 3 政策中的所有條件都會遺失。

如果政策不包含任何條件，對該政策執行的作業可以指定任何有效版本，也可以不指定欄位。

如要瞭解哪些資源支援 IAM 政策中的條件，請參閱 IAM 說明文件。

bindings[]

Binding

將 members 或主體清單與 role 建立關聯。您可以視需要指定 condition，以決定套用 bindings 的方式和時機。每個 bindings 都必須包含至少一個主要元素。

Policy 中的 bindings 最多可參照 1,500 個主體，其中最多 250 個主體可為 Google 群組。每個主體都會計入這些限制。舉例來說，如果 bindings 將 50 個不同角色授予 user:alice@example.com，但沒有授予其他主體，您就可以在 Policy 中將其他 1,450 個主體新增至 bindings。

etag

bytes

etag 用於開放式並行控制，有助防止政策在同時更新時相互覆寫。強烈建議系統在讀取-修改-寫入週期中使用 etag 執行政策更新，以避免發生競爭狀況：getIamPolicy 的回應會傳回 etag，系統應將該 etag 放入 setIamPolicy 的要求中，確保變更會套用至相同版本的政策。

SetIamPolicyRequest

SetIamPolicy 方法的要求訊息。

欄位

欄位
`resource`	`string` 必要：指定政策的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。
`policy`	`Policy` 必要：要套用至 `resource` 的完整政策。政策大小限制為幾十 KB。空白政策是有效政策，但可能會遭到特定 Google Cloud 服務 (例如 Projects) 拒絕。

resource

string

必要：指定政策的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。

policy

Policy

必要：要套用至 resource 的完整政策。政策大小限制為幾十 KB。空白政策是有效政策，但可能會遭到特定 Google Cloud 服務 (例如 Projects) 拒絕。

TestIamPermissionsRequest

TestIamPermissions 方法的要求訊息。

欄位

欄位
`resource`	`string` 必要：要求政策詳細資訊的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。
`permissions[]`	`string` 針對 `resource` 要檢查的權限組合。不允許使用萬用字元 (例如 `` 或 `storage.`)。詳情請參閱「身分與存取權管理總覽」。

resource

string

必要：要求政策詳細資訊的資源。如要瞭解這個欄位的適當值，請參閱「資源名稱」。

permissions[]

string

針對 resource 要檢查的權限組合。不允許使用萬用字元 (例如 * 或 storage.*)。詳情請參閱「身分與存取權管理總覽」。

TestIamPermissionsResponse

TestIamPermissions 方法的回應訊息。

欄位

欄位
`permissions[]`	`string` 已授予呼叫者 `TestPermissionsRequest.permissions` 權限的組合。

permissions[]

string

已授予呼叫者 TestPermissionsRequest.permissions 權限的組合。

Package google.iam.v1 透過集合功能整理內容 你可以依據偏好儲存及分類內容。

索引

IAMPolicy

資料模型

政策結構

繫結

GetIamPolicyRequest

GetPolicyOptions

政策

SetIamPolicyRequest

TestIamPermissionsRequest

TestIamPermissionsResponse

Package google.iam.v1