注意：此文档集适用于 Gemini Enterprise 的 Standard 版、Plus 版、随用随付版和一线员工版。如需查看 Business 版文档，请参阅 Gemini Enterprise - Business 版帮助中心。

Google 会使用 AI 技术将内容翻译成您偏好的语言。AI 翻译可能包含错误。

映射外部身份

企业通常使用身份提供方 (IDP) 管理身份（用户和用户群组）。不过，企业自行构建的自定义应用可让客户创建在相应应用内本地定义的新用户群组。这些应用特有的用户群组或辅助用户 ID 称为外部身份。

为什么设置身份映射？

为了确保 Google 可以正确执行访问权限控制，请将 IDP 身份映射到您计划与 Gemini Enterprise 搭配使用的自定义应用中的任何外部身份。

为了对应用结果应用访问权限控制，Google 会将 IDP 用作可信来源，以确定您的用户可以访问哪些数据。企业通常会将自己的 IdP 关联到其他 SaaS 解决方案，以便员工可以使用一组公司凭证登录并访问所有公司资源。

如果您通过打算连接到应用的自定义应用等应用定义了外部身份，则您的 IDP 就不是访问权限控制的唯一可信来源。

例如，假设“JaneDoe”存在于网域为“example.com”的示例组织中。IDP 中的 ID 定义为“JaneDoe@example.com”。同一用户在自定义应用中的单独 ID 为“JDoe”。IDP 可能不知道此 ID。因此，Gemini Enterprise 不会通过 IDP 接收有关自定义应用 ID 的信息。

在 Gemini Enterprise 中，身份映射存储在您在其中创建并导入映射的身份映射存储区中。如果您计划使用自定义连接器，可以将身份映射存储区绑定到自定义连接器数据存储区，然后使用有关外部身份的信息更新数据存储区的 ACL 元数据。

准备工作

在设置身份映射之前，请先将您的身份提供方关联到 Google Cloud 项目。

准备身份映射条目

准备要导入的身份映射条目。身份映射应采用以下示例中的格式：

{
  "identity_mapping_entries": [
    {
      "external_identity": "u1",
      "user_id": "user1@example.com"
    },
    {
      "external_identity": "u2",
      "user_id": "user2@example.com"
    },
    {
      "external_identity": "gABC",
      "group_id": "groupABC@example.com"
    }
  ]
}

例如，以下图表展示了一个用户-群组成员资格示例，其中 Ext 表示外部群组。此图表展示了外部群组与 IDP 用户和群组之间的关系示例。

外部身份与 IDP 用户和群组的关系。

此用户-群组成员资格图将具有以下映射：

{
  "identity_mapping_entries": [
    {
      "external_identity": "Ext1",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser1@example.com"
    },
    {
      "external_identity": "Ext2",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "user_id": "IDPUser2@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup1@example.com"
    },
    {
      "external_identity": "Ext3",
      "group_id": "IDPGroup2@example.com"
    }
  ]
}

嵌套的身份成员资格（其中的外部身份具有子身份）必须扁平化。

Google 假定连接器会发送外部身份的主 ID。例如，导入群组 ID 而不是群组名称，因为名称可能会在自定义应用中群组的生命周期内发生更改。

设置身份映射

按照以下过程在 Gemini Enterprise 中设置 IDP 与外部身份之间的身份映射。在以下步骤中，您将创建一个身份映射存储区，并导入您准备的身份映射。如果您计划使用自定义连接器，您还将创建一个绑定到身份映射存储区的新数据存储区。

创建身份映射存储区

第一步是设置身份映射存储区。这是存储所有身份映射的父级资源。

创建身份映射存储区时，系统会自动从您关联到 Gemini Enterprise 项目的 IDP 中提取 IDP 配置。

如需创建身份映射存储区，请使用 identityMappingStores.create 方法运行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?identityMappingStoreId=IDENTITY_MAPPING_STORE_ID" \
-d '{
  "name": "projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"
}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。例如：test-id-mapping-store。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth application-default print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores?identityMappingStoreId=test-id-mapping-store" \
-d '{
  "name": "projects/example-project/locations/global/identityMappingStores/test-id-mapping-store"
}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

导入身份映射

创建身份映射存储区后，导入您准备的身份映射条目。您可以使用内嵌来源（方法 1）或从 Cloud Storage（方法 2）导入身份映射。

从 Cloud Storage 导入时，适用以下格式和限制：

允许的格式：输入文件必须采用 NDJSON (.ndjson) 或 JSON Lines (.jsonl) 格式，其中每一行代表一个身份映射条目。
文件大小限制：每个文件不得超过 2 GB。
身份映射数量限制：在导入操作中，您最多可以导入 500,000 个外部身份映射。
文件数量限制：您最多可以在 2,000 列表中指定 inputUris 个文件。如果您使用通配符，则该限制适用于通配符展开后的文件总数。

方法 1：使用内嵌来源导入

如需使用内嵌来源导入身份映射，请使用 importIdentityMappings 方法运行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
LOCATION：数据存储区的多区域： global、us 或 eu
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPINGS_JSON：采用 JSON 格式的已准备好的身份映射。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:importIdentityMappings" \
-d '{"inline_source" : { identity_mapping_entries: { external_identity: "external_id_1", user_id: "testuser1@example.com" } , identity_mapping_entries: { external_identity: "external_id_2", user_id: "testuser2@example.com" }, identity_mapping_entries: { external_identity: "external_id2", group_id: "testgroup1@example.com" } }}'

{
  "name": "projects/862721868538/locations/global/identityMappingStores/test-id-mapping-store/operations/import-identity-mappings-14869487418543288420",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata",
    "successCount": "2",
    "failureCount": "1",
    "totalCount": "3"
  },
  "done": true
}

如果您打算构建自定义连接器并使用外部身份，请转到将自定义数据存储区绑定到身份映射存储区。否则，跳到更新 ACL 元数据。

方法 2：从 Cloud Storage 导入

如需从 Cloud Storage 导入身份映射，请使用 importIdentityMappings 方法运行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: PROJECT_ID" \
"https://ENDPOINT_LOCATION-discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \
-d '{
  "gcsSource": {
    "inputUris": ["gs://BUCKET_NAME/FILE_PATH"]
  },
  "errorConfig": {
    "gcsPrefix": "gs://BUCKET_NAME/ERROR_DIR"
  },
  "reconciliationMode": "FULL"
}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
ENDPOINT_LOCATION：API 请求的多区域。请指定以下某个值：
- us（表示美国多区域）
- eu（表示欧盟多区域）
- global（表示全球位置）
如需了解详情，请参阅为数据存储区指定多区域。
LOCATION：数据存储区的多区域： global、us 或 eu
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
BUCKET_NAME：Cloud Storage 存储桶的名称。
FILE_PATH：Cloud Storage 中身份映射文件的路径。
ERROR_DIR：Cloud Storage 中将存储错误日志的目录。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" -H "x-goog-user-project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:importIdentityMappings" \
-d '{
  "gcsSource": {
    "inputUris": ["gs://example-bucket/identity_mappings.json"]
  },
  "errorConfig": {
    "gcsPrefix": "gs://example-bucket/errors"
  },
  "reconciliationMode": "FULL"
}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store/operations/import-identity-mappings-14869487418543288420",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata",
    "successCount": "2",
    "failureCount": "1",
    "totalCount": "3"
  },
  "done": true
}

如果您打算构建自定义连接器并使用外部身份，请转到将自定义数据存储区绑定到身份映射存储区。否则，跳到更新 ACL 元数据。

将自定义数据存储区绑定到身份映射存储区

只有在构建自定义连接器时，才需要执行此过程。如果您不构建自定义连接器，请跳过此步骤。

对于自定义连接器，需要先将身份映射存储区绑定到数据存储区，然后才能将外部身份与文档相关联。仅在创建数据存储区期间允许设置此字段。

如需将数据存储区绑定到身份映射存储区，请在创建数据存储区期间使用 Datastores.create 方法指定 identity_mapping_store。
```
curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json"  \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/collections/default_collection/dataStores?dataStoreId=DATA_STORE_ID \
-d '{
    ...
    "identity_mapping_store": "IDENTITY_MAPPING_STORE_NAME"
}'
```
替换以下内容：
- PROJECT_ID：您的项目的 ID。
- DATA_STORE_ID：您要创建的数据存储区的 ID。此 ID 只能包含小写字母、数字、下划线和连字符。
- IDENTITY_MAPPING_STORE_NAME：身份映射存储区的完整资源名称。例如：projects/exampleproject/locations/global/identityMappingStores/test-id-mapping-store。创建数据存储区后，此名称无法更新。

添加 ACL 元数据

在文档的 AclInfo 对象中添加 ACL 元数据。

当用户发送搜索请求并提取 ACL 元数据包含外部身份的文档时，系统会评估这些外部身份。如果用户的身份（groupID 或 userID）映射到与文档关联的外部身份 (externalEntityId)，则用户可以访问该文档。

例如，假设您为 Jira 创建了一个自定义连接器。某些 IDP 用户、某些 IDP 群组和管理员角色可以访问给定的 Jira 问题。为了让这些人能够在搜索结果中看到该问题，您可以创建身份映射存储区，并将 IDP 用户和群组映射到 Jira 特定的外部身份。将身份映射存储区绑定到 Jira 数据存储区。然后，在 Jira 数据存储区中创建文档，其中 aclInfo 配置有应有权访问这些文档的 IDP 用户、IDP 群组和外部身份。

如需使用有关外部身份的信息更新 ACL 元数据，请使用以下格式指定外部身份以及关联的用户和群组 ID。

{
  "aclInfo": {
    "readers": [
      {
        "principals": [
          {
            "groupId": "group_1"
          },
          {
            "userId": "user_1"
          },
          {
            "externalEntityId": "external_id1"
          }

        ]
      }
    ]
  }
}

如需详细了解如何更新 ACL 元数据，请参阅配置具有访问权限控制的数据源。

管理身份映射

您可以列出身份存储区中的身份映射，也可以通过内嵌来源定义身份存储区或使用过滤条件来完全清除身份存储区。

可用于身份映射的管理任务包括：

列出身份映射
使用内嵌来源进行完全清除
使用过滤条件进行完全清除

列出身份映射

如需列出身份映射，请使用 listIdentityMappings方法运行以下命令：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:listIdentityMappings?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

替换以下内容：

PROJECT_ID：您的项目的 ID。
PAGE_SIZE：要返回的身份映射存储区的数量上限。如果未指定，则默认为 100。允许的最大值为 1,000。高于 1,000 的值会强制转换为 1,000。
PAGE_TOKEN：从之前的 ListIdentityMappingStores 调用接收的页面令牌。利用其进行后续页面检索。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: example-project" \
https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store:listIdentityMappings

{
  "identityMappingEntries": [
    {
      "externalIdentity": "external_group2",
      "groupId": "example-group@google.com"
    },
    {
      "externalIdentity": "external_id_1",
      "userId": "example-user@google.com"
    }
  ],
  "nextPageToken": "gNiNWOiRTMxEWMwATLmNDMh1CO0IjMtADMwATLkRWYkZTZ3YDJawB2h-LEG8ro3XLCLIBZ2YmNz"
}

使用内嵌来源进行完全清除

您可以提供一个 JSON 文件，其中包含要完全清除的身份，从而从身份映射存储区中完全清除指定的条目。

如需使用内嵌来源完全清除身份映射，请使用 purgeIdentityMappings 方法运行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。
IDENTITY_MAPPINGS_JSON：要完全清除的身份映射。

使用过滤条件进行完全清除

您可以按更新时间、外部身份或所有条目过滤条目，从而完全清除身份映射存储区中指定的条目。

如需使用过滤条件完全清除身份映射，请使用 purgeIdentityMappings 方法运行以下命令：

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:purgeIdentityMappings" \
-d '{"identity_mapping_store":"IDENTITY_MAPPING_STORE_NAME", "filter": "FILTER_CONDITION"}'

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。
FILTER_CONDITION：以下过滤条件类型之一：

更新时间。例如 update_time > "2012-04-23T18:25:43.511Z" AND update_time < "2012-04-23T18:30:43.511Z">。
外部身份。例如 external_id = "id1"。
所有身份映射。例如 *。

命令和结果示例

curl -X POST \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/ucs-ga-fishfood-1/locations/global/identityMappingStores/test-id-mapping-store:purgeIdentityMappings" \
-d '{"identity_mapping_store":"test-id-mapping-store", "filter": "*"}'

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store/operations/purge-identity-mappings-200445172458892000",
  "metadata": {
    "@type": "type.googleapis.com/google.cloud.discoveryengine.v1.IdentityMappingEntryOperationMetadata"
  }
}

管理身份映射存储区

您可以获取、删除、列出和完全清除身份映射存储区。

获取身份映射存储区

如需获取身份映射存储区，请使用 identityMappingStores.get 方法运行以下命令：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: example-project" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores/test-id-mapping-store"

{
  "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
  "idpConfig": {
    "idpType": "GSUITE"
  }
}

列出身份映射存储区

如需列出身份映射存储区，请使用 identityMappingStores.list 方法运行以下命令：

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores?page_size=PAGE_SIZE&page_token=PAGE_TOKEN"

替换以下内容：

PROJECT_ID：您的项目的 ID。
PAGE_SIZE：要返回的身份映射存储区的数量上限。如果未指定，则默认为 100。允许的最大值为 1,000。高于 1,000 的值会强制转换为 1,000。
PAGE_TOKEN：从之前的 ListIdentityMappingStores 调用接收的页面令牌。利用其进行后续页面检索。

命令和结果示例

curl -X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H  "Content-Type: application/json" \
-H "x-goog-user-project: ucs-ga-fishfood-1" \
"https://discoveryengine.googleapis.com/v1/projects/example-project/locations/global/identityMappingStores"

{
  "identityMappingStores": [
    {
      "name": "projects/12345/locations/global/identityMappingStores/test-id-mapping-store",
      "idpConfig": {
        "idpType": "GSUITE"
      }
    }
  ]
}

删除身份映射存储区

如需删除身份映射存储区，该存储区不得绑定到数据存储区，并且身份映射存储区中不得存在任何身份映射。

如需删除身份映射存储区，请使用 identityMappingStores.delete方法运行以下命令：

curl -X DELETE \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
-H "Content-Type: application/json" \
-H "X-Goog-User-Project: PROJECT_ID" \
"https://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID"

替换以下内容：

PROJECT_ID：您的项目的 ID。
IDENTITY_MAPPING_STORE_ID：身份映射存储区的唯一 ID。
IDENTITY_MAPPING_STORE_NAME：身份映射存储区名称。

映射外部身份 使用集合让一切井井有条 根据您的偏好保存内容并对其进行分类。

为什么设置身份映射？

准备工作

准备身份映射条目

设置身份映射

创建身份映射存储区

命令和结果示例

导入身份映射

方法 1：使用内嵌来源导入

命令和结果示例

方法 2：从 Cloud Storage 导入

命令和结果示例

将自定义数据存储区绑定到身份映射存储区

添加 ACL 元数据

管理身份映射

列出身份映射

命令和结果示例

使用内嵌来源进行完全清除

使用过滤条件进行完全清除

命令和结果示例

管理身份映射存储区

获取身份映射存储区

命令和结果示例

列出身份映射存储区

命令和结果示例

删除身份映射存储区

映射外部身份