이 페이지는 Cloud Translation API를 통해 번역되었습니다.

IAM을 사용한 Conversational Analytics API 액세스 제어

Conversational Analytics API는 액세스 제어를 위해 Identity and Access Management (IAM)를 사용하므로 데이터 에이전트를 공유하고 데이터 에이전트를 만들고, 관리하고, 상호작용할 수 있는 권한이 있는 사용자를 제어할 수 있습니다. 이 페이지에서는 이러한 권한을 부여하기 위해 주 구성원 (예: 사용자, 그룹, 서비스 계정)에게 할당할 수 있는 사전 정의된 IAM 역할을 설명합니다.

시작하기 전에

대화형 분석 API IAM 역할을 할당하는 데 필요한 권한을 얻으려면 관리자에게 대화형 분석 API가 사용 설정된 프로젝트에 대한 프로젝트 IAM 관리자(roles/resourcemanager.projectIamAdmin) IAM 역할을 부여해 달라고 요청하세요. 역할 부여에 대한 자세한 내용은 프로젝트, 폴더, 조직에 대한 액세스 관리를 참조하세요.

커스텀 역할이나 다른 사전 정의된 역할을 통해 필요한 권한을 얻을 수도 있습니다.

대화형 분석 API IAM 역할 개요

Conversational Analytics API의 사전 정의된 IAM 역할은 데이터 에이전트를 만들고, 관리하고, 상호작용할 수 있는 사용자를 세부적으로 제어합니다. 이 섹션에서는 IAM 역할을 할당하여 데이터 에이전트를 공유하는 방법을 설명하고 다른 일반적인 사용자 작업에 필요한 IAM 역할을 설명합니다.

프로젝트 수준에서 역할을 부여하여 프로젝트 내 모든 에이전트에 권한을 제공할 수 있습니다. 대신 특정 에이전트에 대한 액세스 권한을 제어하려면 에이전트 소유자 (Gemini 데이터 분석 데이터 에이전트 소유자 역할이 있는 주 구성원)가 해당 에이전트의 IAM 정책을 프로그래매틱 방식으로 수정하면 됩니다.

다음 다이어그램은 에이전트 소유자가 특정 에이전트에 대한 액세스를 관리하는 방법을 보여줍니다.

에이전트 소유자는 다른 사용자에게 데이터 에이전트 편집자 및 데이터 에이전트 사용자 역할을 부여합니다.

이 시나리오에서는 Gemini 데이터 분석 데이터 에이전트 생성자 역할이 있는 수석 데이터 애널리스트가 에이전트를 만듭니다. 사용자가 에이전트를 만들면 해당 에이전트에 대해 Gemini 데이터 분석 데이터 에이전트 소유자 역할이 자동으로 부여됩니다. 에이전트 소유자인 수석 데이터 분석가는 IAM 정책을 설정하여 에이전트에 대한 액세스 권한을 관리하고 팀 구성원에게 다음 역할을 부여합니다.

Gemini 데이터 분석 데이터 에이전트 편집자: 에이전트 소유자가 주니어 데이터 분석가에게 이 역할을 부여합니다. 이 역할을 사용하면 주니어 분석가가 에이전트의 구성을 수정하고 에이전트와 채팅할 수 있습니다.
Gemini 데이터 분석 데이터 에이전트 사용자: 에이전트 소유자가 에이전트의 구성을 수정할 필요가 없는 팀 구성원에게 이 역할을 부여합니다. 이 역할을 통해 팀 구성원은 에이전트와 채팅할 수 있습니다.

일반적인 사용자 태스크에 필요한 역할

할당할 역할을 결정하려면 다음 일반적인 사용자 작업을 고려하세요.

새 데이터 에이전트 만들기: 프로젝트 내에서 새 데이터 에이전트를 만들어야 하는 사용자에게 Gemini 데이터 분석 데이터 에이전트 생성자 역할을 할당합니다.
에이전트 공유: 에이전트 권한을 관리하여 다른 주 구성원과 에이전트를 공유해야 하는 사용자에게 Gemini 데이터 분석 데이터 에이전트 소유자 역할을 할당합니다.
에이전트 권한 관리: 에이전트 권한을 관리하여 다른 사용자와 에이전트를 공유해야 하거나 에이전트를 삭제하는 기능을 포함하여 에이전트를 가장 높은 수준으로 제어해야 하는 사용자에게 Gemini 데이터 분석 데이터 에이전트 소유자 역할을 할당합니다. 사용자가 에이전트를 만들면 시스템은 특정 에이전트의 해당 사용자에게 이 역할을 자동으로 부여합니다.
에이전트 구성 수정: 컨텍스트 또는 데이터 소스 매핑과 같은 에이전트 구성을 수정하는 사용자에게 Gemini 데이터 분석 데이터 에이전트 편집자 역할을 할당합니다. 이러한 사용자에게는 에이전트를 공유하거나 삭제할 수 있는 권한이 없습니다.
에이전트와 채팅: 주로 질문을 하고 응답을 받아 에이전트와 상호작용하는 사용자나 애플리케이션에 Gemini 데이터 분석 데이터 에이전트 사용자 역할을 할당합니다.
에이전트 구성 보기: 에이전트 구성을 보기 위해 읽기 전용 액세스 권한이 필요한 사용자에게 Gemini 데이터 분석 데이터 에이전트 뷰어 역할을 할당합니다.
인라인 컨텍스트를 사용하여 채팅: 사용자가 각 요청 내에서 대화의 모든 컨텍스트를 제공하는 스테이트리스(Stateless) 모드에서 API와 상호작용하는 사용자나 애플리케이션에 Gemini 데이터 분석 스테이트리스(Stateless) 채팅 사용자 역할을 할당합니다.

대화형 분석 API의 사전 정의된 역할

다음 표에서는 대화형 분석 API의 사전 정의된 역할을 설명합니다. 사전 정의된 역할이 원하는 권한 집합을 제공하지 못하는 경우 자체 맞춤 역할을 만들 수도 있습니다.

역할	권한
Gemini 데이터 분석 데이터 에이전트 생성자(`roles/geminidataanalytics.dataAgentCreator`) 주 구성원에게 특정 프로젝트에 새 데이터 에이전트 리소스를 만들 수 있는 권한을 부여합니다. 주 구성원이 에이전트를 만들면 시스템은 해당 주 구성원에게 특정 에이전트에 대한 `dataAgentOwner` 역할을 자동으로 부여합니다.	`geminidataanalytics.dataAgents.create`
Gemini 데이터 분석 데이터 에이전트 소유자(`roles/geminidataanalytics.dataAgentOwner`) 주 구성원에게 에이전트 공유 및 삭제를 포함하여 프로젝트 내 모든 에이전트의 수명 주기에 대한 전체 제어 권한을 부여합니다. 이 역할은 에이전트 공유를 관리할 수 있는 신뢰할 수 있는 주 구성원을 위한 역할입니다. 이 역할은 `dataAgentEditor`, `dataAgentUser`, `dataAgentViewer` 역할의 모든 권한을 상속합니다. 이 역할이 부여된 주 구성원은 에이전트를 공유하고 삭제할 수 있습니다.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update` `geminidataanalytics.dataAgents.delete` `geminidataanalytics.dataAgents.getIamPolicy` `geminidataanalytics.dataAgents.setIamPolicy`
Gemini 데이터 분석 데이터 에이전트 편집자(`roles/geminidataanalytics.dataAgentEditor`) 기존 에이전트 구성을 수정하고 관리할 수 있는 권한을 부여합니다. 이 역할은 `dataAgentUser` 및 `dataAgentViewer` 역할의 모든 권한을 상속합니다.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat` `geminidataanalytics.dataAgents.update`
Gemini 데이터 분석 데이터 에이전트 사용자(`roles/geminidataanalytics.dataAgentUser`) 주 구성원에게 액세스 권한이 부여된 특정 에이전트와 채팅할 수 있는 권한을 주 구성원에게 부여합니다. 이 역할은 `dataAgentViewer` 역할의 모든 권한을 상속합니다.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get` `geminidataanalytics.dataAgents.chat`
Gemini 데이터 분석 데이터 에이전트 뷰어(`roles/geminidataanalytics.dataAgentViewer`) 주 구성원에게 에이전트 구성을 나열하고 볼 수 있는 읽기 전용 권한을 부여합니다. 이 역할로는 에이전트와 채팅할 수 없습니다.	`geminidataanalytics.dataAgents.list` `geminidataanalytics.dataAgents.get`
Gemini 데이터 분석 스테이트리스(Stateless) 채팅 사용자(`roles/geminidataanalytics.dataAgentStatelessUser`) 주 구성원에게 스테이트리스(Stateless) 모드에서 Chat API를 호출할 수 있는 권한을 부여합니다. 스테이트리스(Stateless) 채팅을 사용하면 컨텍스트가 생성 중에 에이전트 구성에 명시적으로 저장되는 대신 요청에 직접 제공됩니다.	`geminidataanalytics.chat`

IAM 역할 부여

프로젝트 수준 또는 특정 상담사에 대화형 분석 API IAM 역할을 부여할 수 있습니다. 프로젝트 수준에서 역할을 부여하면 주 구성원에게 해당 프로젝트의 모든 에이전트에 대한 동일한 권한이 부여되지만 특정 에이전트에 정책을 설정하면 더 세부적인 제어가 가능합니다.

대화형 분석 API의 사전 정의된 IAM 역할은 geminidataanalytics 서비스의 일부입니다. 이러한 역할의 기술 이름은 roles/geminidataanalytics.ROLE_NAME 패턴을 따릅니다. Google Cloud 콘솔에서 Gemini 데이터 분석 서비스를 필터링하여 이러한 역할을 찾을 수 있습니다.

프로젝트의 모든 에이전트에 역할 부여

Google Cloud 콘솔 또는 Google Cloud CLI를 사용하여 전체 프로젝트에 대한 역할을 부여합니다.

콘솔

Google Cloud 콘솔에서 주 구성원에게 역할을 부여하려면 다음 단계를 완료합니다.

Google Cloud 콘솔에서 IAM 페이지로 이동합니다.

IAM으로 이동
액세스 권한 부여를 클릭합니다.
새 주 구성원 필드에 사용자, 그룹 또는 서비스 계정의 이메일 주소를 입력합니다.
역할 선택 메뉴에서 Gemini 데이터 분석을 필터링하여 대화형 분석 API에 사용할 수 있는 IAM 역할을 확인합니다.
Gemini 데이터 분석 데이터 에이전트 사용자와 같은 적절한 역할을 선택합니다.
저장을 클릭합니다.

gcloud

gcloud CLI를 사용하여 역할을 부여하려면 다음 단계를 완료합니다.

Google Cloud 에 로그인하고 프로젝트를 설정합니다.

gcloud auth login
gcloud config set project project_id

원하는 경우 프로젝트에 부여할 수 있는 대화형 분석 API IAM 역할을 나열하려면 다음과 같이 gcloud iam list-grantable-roles 명령어를 사용합니다.

gcloud iam list-grantable-roles //cloudresourcemanager.googleapis.com/projects/project_id --filter "geminidataanalytics"

gcloud projects add-iam-policy-binding 명령어를 사용하여 주 구성원에게 역할을 부여합니다.

사용자에게 역할을 부여하려면 다음 명령어를 사용합니다.

gcloud projects add-iam-policy-binding project_id --member='user:user_email' --role='roles/gda_grantable_role'

서비스 계정에 역할을 할당하려면 다음 명령어를 사용합니다.

gcloud projects add-iam-policy-binding project_id --member='serviceAccount:service_account_email' --role='roles/gda_grantable_role'

이전 안내에서 샘플 값을 다음과 같이 바꿉니다.

project_id: Google Cloud 프로젝트 ID입니다.
user_email: 사용자의 이메일 주소로 바꿉니다(예: test-user@gmail.com)
service_account_email: 서비스 계정의 이메일 주소로 바꿉니다(예: test-proj@example.domain.com)
gda_grantable_role: 부여할 특정 대화형 분석 API IAM 역할로 바꿉니다(예: geminidataanalytics.dataAgentCreator).

특정 에이전트의 역할 부여

특정 데이터 에이전트의 액세스 권한을 관리하려면 해당 에이전트의 허용 정책을 프로그래매틱 방식으로 수정해야 합니다. 이 프로세스는 현재 정책을 읽고 수정하고 다시 쓰는 표준 읽기-수정-쓰기 패턴을 따릅니다.

다음 샘플은 데이터 에이전트에 대한 IAM 정책을 가져오고 설정하는 요청 본문을 보여줍니다.

HTTP

에이전트의 기존 정책을 가져오려면 다음 요청 본문과 함께 :getIamPolicy 엔드포인트에 POST 요청을 전송합니다.

{
  "resource": "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
}

에이전트의 정책을 설정하려면 다음 요청 본문을 사용하여 :setIamPolicy 엔드포인트에 POST 요청을 보냅니다.

{
  "policy": {
    "bindings": [
      {
        "role": "ROLE",
        "members": [
          "user:EMAIL"
        ]
      }
    ]
  }
}

다음을 바꿉니다.

PROJECT_ID: Google Cloud 프로젝트 ID입니다.
AGENT_ID: 정책을 가져오거나 설정할 데이터 에이전트의 ID입니다.
ROLE: 부여할 역할입니다(예: roles/geminidataanalytics.dataAgentUser).
EMAIL: 사용자의 이메일 주소로 바꿉니다(예: test-user@gmail.com)

전체 예는 데이터 에이전트에 대한 IAM 정책 가져오기 및 데이터 에이전트에 대한 IAM 정책 설정을 참고하세요.

Python SDK

에이전트의 기존 정책을 가져오려면 다음 샘플 요청과 같이 get_iam_policy 메서드를 사용하세요.

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
request = iam_policy_pb2.GetIamPolicyRequest(
            resource=resource,
        )

에이전트의 정책을 설정하려면 다음 샘플 요청과 같이 set_iam_policy 메서드를 사용하세요.

resource = "projects/PROJECT_ID/locations/global/dataAgents/AGENT_ID"
policy = policy_pb2.Policy(
    bindings=[
        policy_pb2.Binding(
            role="ROLE",
            members=["user:EMAIL"]
        )
    ]
)
request = iam_policy_pb2.SetIamPolicyRequest(
    resource=resource,
    policy=policy
)