Cloud Search Query API에서는 도메인의 라이선스가 부여된 사용자에게 속한 OAuth 사용자 인증 정보를 사용하여 API 호출을 승인해야 합니다. 기본적으로 색인 생성 및 구성 API에 액세스하는 데 사용되는 서비스 계정은 Cloud Search 또는 Google Workspace 라이선스가 있는 도메인 사용자가 아니므로 쿼리 API 호출에 사용할 수 없습니다. 쿼리 API 호출 인증에 서비스 계정을 사용하려는 경우 도메인 관리자가 계정에 사용자 데이터에 대한 도메인 전체 액세스 권한을 부여할 수 있습니다. 이것을 도메인 전체 권한 위임이라고 합니다. 위임된 권한이 있는 서비스 계정은 Cloud Search 액세스 권한이 있는 사용자를 포함한 모든 사용자를 가장할 수 있습니다.
도메인의 관리 콘솔에서 기본 메뉴menu > 보안 > 액세스 및 데이터 컨트롤 > API 컨트롤로 이동합니다.
도메인 전체 위임 창에서 도메인 전체 위임 관리를 선택합니다.
새로 추가를 클릭합니다.
클라이언트 ID 필드에 위의 서비스 계정 생성 단계에서 얻은 클라이언트 ID를 입력합니다.
OAuth 범위 필드에 애플리케이션에 필요한 범위를 쉼표로 구분된 목록으로 입력합니다. Query API를 사용하는 검색 애플리케이션의 경우 https://www.googleapis.com/auth/cloud_search.query 범위를 사용합니다.
승인을 클릭합니다.
이제 서비스 계정은 Cloud Search Query API에 대한 도메인 전체 액세스 권한을 가지며 이 범위에 있는 도메인의 모든 사용자를 가장할 수 있습니다. 도메인 사용자를 대신하여 승인된 Cloud Search API 서비스 객체를 인스턴스화할 수 있습니다.
Cloud Search API 서비스 객체 인스턴스화
이 섹션에서는 Cloud Search API 서비스 객체를 인스턴스화한 다음 승인해서 OAuth 2.0과 서비스 계정의 사용자 인증 정보를 사용하여 API 요청을 실행하고 Google Workspace 도메인 전체 위임을 수행하는 방법을 보여줍니다. 예시는 JSON 형식의 비공개 키 파일에서 서비스 계정 정보를 읽습니다.
자바
importjava.util.Collections;importjava.io.FileInputStream;importcom.google.api.client.googleapis.auth.oauth2.GoogleCredential;importcom.google.api.client.http.HttpTransport;importcom.google.api.client.json.JsonFactory;importcom.google.api.services.cloudsearch.v1.CloudSearch;importcom.google.api.services.cloudsearch.v1.CloudSearchScopes;.../** Path to the Service Account's Private Key file */privatestaticfinalStringSERVICE_ACCOUNT_FILE_PATH="/path/to/key.json";/** * Build and return a Cloud Search service object authorized with the service * account that acts on behalf of the given user. * * @param userEmail The email of the user to impersonate. Needs permissions to access Cloud Search. * @return CloudSearch service object that is ready to make requests. */publicstaticCloudSearchgetCloudSearchAPIService(StringuserEmail)throwsFileNotFoundException,IOException{FileInputStreamcredsFile=newFileInputStream(SERVICE_ACCOUNT_FILE_PATH);GoogleCredentialinit=GoogleCredential.fromStream(credsFile);HttpTransporthttpTransport=init.getTransport();JsonFactoryjsonFactory=init.getJsonFactory();GoogleCredentialcreds=newGoogleCredential.Builder().setTransport(httpTransport).setJsonFactory(jsonFactory).setServiceAccountId(init.getServiceAccountId()).setServiceAccountPrivateKey(init.getServiceAccountPrivateKey()).setServiceAccountScopes(Collections.singleton(CloudSearchScopes.CLOUD_SEARCH_QUERY)).setServiceAccountUser(userEmail).build();CloudSearchservice=newCloudSearch.Builder(httpTransport,jsonFactory,creds).build();returnservice;}
Python
fromgoogle.oauth2importservice_accountfromgoogleapiclient.discoveryimportbuild# Path to the Service Account's Private Key fileSERVICE_ACCOUNT_FILE_PATH="/path/to/key.json"defcreate_query_api_service(user_email):"""Build and return a CloudSearch service object authorized with the service account that acts on behalf of the given user. Args: user_email: The email of the user to impersonate. Needs permissions to access Cloud Search. Returns: Cloud Search Query API service object that is ready to make requests. """credentials=service_account.Credentials.from_service_account_file(SERVICE_ACCOUNT_FILE_PATH,scopes=['https://www.googleapis.com/auth/cloud_search.query'])delegated_credentials=credentials.with_subject(user_email)returnbuild("cloudsearch","v1",credentials=delegated_credentials)
[null,null,["최종 업데이트: 2025-08-29(UTC)"],[],[],null,["# Perform Google Workspace domain-wide delegation of authority\n\nThe Cloud Search Query API requires that API calls are authorized using OAuth\ncredentials belonging to a licensed user in your domain. By default, service\naccounts, which are used to access the indexing and configuration APIs, cannot\nbe used for query API calls because they are not domain users with Cloud Search\nor Google Workspace licenses. If you wish to use a service account when\nauthenticating query API calls, a domain administrator can grant the account\ndomain-wide access to user data --- this is known as\n*domain-wide delegation of authority*. A service account with delegated\nauthority can impersonate any user, including users with access to Cloud Search.\n\nCreate the service account and credentials\n------------------------------------------\n\nIf you do not yet have service account credentials, refer to\n[Create service account credentials](/workspace/cloud-search/docs/guides/project-setup#create_service_account_credentials).\n\nDelegate domain-wide authority to your service account\n------------------------------------------------------\n\nTo access user data on a Google Workspace domain, the service account that\nyou created needs to be granted access by a super administrator for the domain.\nFor more information about domain-wide delegation, see\n[Control Google Workspace API access with domain-wide delegation](https://support.google.com/a/answer/162106).\n\nTo delegate domain-wide authority to a service account:\n\n1. From your domain's [Admin console](http://admin.google.com), go to **Main menu** menu \\\u003e **Security** \\\u003e **Access and data control** \\\u003e **API controls**.\n2. In the **Domain wide delegation** pane, select **Manage Domain Wide\n Delegation**.\n\n3. Click **Add new**.\n\n4. In the **Client ID** field, enter the client ID obtained from the\n service account creation steps above.\n\n5. In the **OAuth Scopes** field, enter a comma-delimited list of the scopes\n required for your application. Use the scope\n `https://www.googleapis.com/auth/cloud_search.query` for search applications\n using the Query API.\n\n6. Click **Authorize**.\n\nYour service account now has domain-wide access to the Cloud Search Query API,\nand can impersonate any user of your domain in this scope. You are ready to\ninstantiate an authorized Cloud Search API service object on behalf of your\ndomain's users.\n| **Note:** To access the Query API, your service must impersonate a user with access to Cloud Search. Additionally, the user must have logged in at least once and accepted the Google Workspace Terms of Service. The Query API will return results with ACLs according to the permissions of the impersonated user.\n\nInstantiate a Cloud Search API service object\n---------------------------------------------\n\nThis section shows how to instantiate a Cloud Search API service object and then\nauthorize it to make API requests using OAuth 2.0 and your service account's\ncredentials to perform Google Workspace domain-wide delegation. The examples\nread the service account's information from the JSON-formatted private key file. \n\n### Java\n\n import java.util.Collections;\n import java.io.FileInputStream;\n import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;\n import com.google.api.client.http.HttpTransport;\n import com.google.api.client.json.JsonFactory;\n import com.google.api.services.cloudsearch.v1.CloudSearch;\n import com.google.api.services.cloudsearch.v1.CloudSearchScopes;\n ...\n\n /** Path to the Service Account's Private Key file */\n private static final String SERVICE_ACCOUNT_FILE_PATH = \"/path/to/key.json\";\n\n /**\n * Build and return a Cloud Search service object authorized with the service\n * account that acts on behalf of the given user.\n *\n * @param userEmail The email of the user to impersonate. Needs permissions to access Cloud Search.\n * @return CloudSearch service object that is ready to make requests.\n */\n public static CloudSearch getCloudSearchAPIService(String userEmail)\n throws FileNotFoundException, IOException {\n\n FileInputStream credsFile = new FileInputStream(SERVICE_ACCOUNT_FILE_PATH);\n\n GoogleCredential init = GoogleCredential.fromStream(credsFile);\n\n HttpTransport httpTransport = init.getTransport();\n JsonFactory jsonFactory = init.getJsonFactory();\n\n GoogleCredential creds = new GoogleCredential.Builder()\n .setTransport(httpTransport)\n .setJsonFactory(jsonFactory)\n .setServiceAccountId(init.getServiceAccountId())\n .setServiceAccountPrivateKey(init.getServiceAccountPrivateKey())\n .setServiceAccountScopes(Collections.singleton(CloudSearchScopes.CLOUD_SEARCH_QUERY))\n .setServiceAccountUser(userEmail)\n .build();\n\n CloudSearch service = new CloudSearch.Builder(httpTransport, jsonFactory, creds).build();\n\n return service;\n }\n\n### Python\n\n from google.oauth2 import service_account\n from googleapiclient.discovery import build\n\n # Path to the Service Account's Private Key file\n SERVICE_ACCOUNT_FILE_PATH = \"/path/to/key.json\"\n\n def create_query_api_service(user_email):\n \"\"\"Build and return a CloudSearch service object authorized with the service\n account that acts on behalf of the given user.\n\n Args:\n user_email: The email of the user to impersonate. Needs permissions to access Cloud Search.\n Returns:\n Cloud Search Query API service object that is ready to make requests.\n \"\"\"\n credentials = service_account.Credentials.from_service_account_file(\n SERVICE_ACCOUNT_FILE_PATH,\n scopes=['https://www.googleapis.com/auth/cloud_search.query'])\n\n delegated_credentials = credentials.with_subject(user_email)\n\n return build(\"cloudsearch\", \"v1\", credentials=delegated_credentials)"]]
