企業通常會使用身分識別資訊提供者 (IDP) 管理身分 (使用者和使用者群組)。不過，企業內部建構的自訂應用程式可讓客戶建立新的使用者群組，這些群組是在該應用程式中本機定義。這些應用程式專屬的使用者群組或次要使用者 ID 稱為「外部身分」。
為什麼要設定識別資訊對應？
為確保 Google 能正確執行存取權控管，請將 IDP 身分對應至您打算與 Gemini Enterprise 搭配使用的自訂應用程式中的任何外部身分。
如要對應用程式結果套用存取權控管機制，Google 會使用 IDP 做為資訊來源，判斷使用者可存取哪些資料。企業通常會將 IDP 連線至其他 SaaS 解決方案，讓員工使用一組公司憑證登入及存取所有公司資源。
如果您透過應用程式 (例如自訂應用程式) 定義外部身分，並打算連結至應用程式，則 IDP 並非存取權控管的唯一可靠資料來源。
舉例來說，假設「JaneDoe」存在於 Example Organization 中，網域為「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 使用者和群組之間的關係範例。
這個使用者群組成員資格圖表會包含下列對應：
{
"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 與外部身分之間的 ID 對應。在接下來的步驟中，您將建立身分對應儲存區，並匯入您準備的身分對應。如果您打算使用自訂連結器，也需要建立繫結至身分識別對應儲存區的新資料儲存區。
建立身分對應商店
首先，請設定身分對應商店。這是儲存所有身分識別對應的父項資源。
建立身分對應存放區時，系統會自動從您連結至 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。
匯入識別資訊對應
建立識別資訊對應儲存空間後，請匯入您準備的識別資訊對應項目。
如要匯入身分對應，請使用
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://discoveryengine.googleapis.com/v1/projects/PROJECT_ID/locations/global/identityMappingStores/IDENTITY_MAPPING_STORE_ID:importIdentityMappings" \ -d '{"inline_source" : IDENTITY_MAPPINGS_JSON}'更改下列內容：
PROJECT_ID：專案 ID。IDENTITY_MAPPING_STORE_ID：身分對應商店的專屬 ID。IDENTITY_MAPPINGS_JSON：JSON 格式的準備好的身分對應。
接著，如果您打算建立自訂連接器並使用外部身分，請前往「將自訂資料存放區繫結至身分對應存放區」。否則，請跳到「更新 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。允許的最大值為 1000。超出的數值將一律指定為 1000。PAGE_TOKEN：接收自前一個ListIdentityMappingStores呼叫的網頁權杖。提供此項目即可擷取後續網頁。
使用內嵌來源清除
您可以提供要清除身分的 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"。 - 所有識別資訊對應。例如
*。
管理身分對應商店
您可以取得、刪除、列出及清除身分對應儲存空間。
取得識別資訊對應儲存空間
如要取得身分對應存放區，請使用
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：身分對應儲存區名稱。
列出識別資訊對應儲存空間
如要列出身分對應儲存空間，請使用
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。允許的最大值為 1000。超出的數值將一律指定為 1000。PAGE_TOKEN：接收自前一個ListIdentityMappingStores呼叫的網頁權杖。提供此項目即可擷取後續網頁。
刪除身分識別對應儲存空間
如要刪除身分對應儲存庫，該儲存庫不得繫結至資料儲存庫，且身分對應儲存庫中不得有任何身分對應。
如要刪除身分對應存放區，請使用
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：身分對應儲存區名稱。