Cloud Search Query API 要求使用属于您网域中已获许可用户的 OAuth 凭据来授权 API 调用。默认情况下，用于访问索引和配置 API 的服务账号不能用于查询 API 调用，因为这些账号并非具有 Cloud Search 或 Google Workspace 许可的网域用户。如果您希望在对查询 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 格式的私钥文件中读取服务账号的信息。
Java
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,["最后更新时间 (UTC)：2025-08-29。"],[],[],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)"]]
