执行 Google Workspace 全网域授权

Cloud Search Query API 要求使用属于您网域中已获许可用户的 OAuth 凭据来授权 API 调用。默认情况下，用于访问索引和配置 API 的服务账号不能用于查询 API 调用，因为这些账号并非具有 Cloud Search 或 Google Workspace 许可证的网域用户。如果您希望在对查询 API 调用执行身份验证时使用服务账号，则网域管理员可以授予该账号对用户数据的全网域访问权限 - 这就称为全网域授权。获得此授权的服务账号可以模拟任何用户，包括有权访问 Cloud Search 的用户。

创建服务账号和凭据

如果您还没有服务账号凭据，请参阅创建服务账号凭据。

向您的服务账号进行全网域授权

如需访问 Google Workspace 网域中的用户数据，您创建的服务账号需要获得该网域的超级用户授予的访问权限。如需详细了解全网域授权，请参阅使用全网域授权功能控制 Google Workspace API 访问权限。

如需向服务账号委派全网域授权，请执行以下操作：

  1. 在网域的管理控制台中，依次前往主菜单 > 安全性 > 访问权限和数据控件 > API 控件。

  2. 在全网域授权窗格中，选择管理全网域授权。

  3. 点击新增。

  4. 在客户端 ID 字段中，输入在前述服务账号创建步骤中获得的客户端 ID。

  5. 在 OAuth 范围字段中，输入应用所需的范围的逗号分隔列表。对于使用 Query API 的搜索应用，请使用 https://www.googleapis.com/auth/cloud_search.query 这一作用域。

  6. 点击授权。

这样，您的服务账号即可获得对 Cloud Search Query API 的全网域访问权限，并且可以在该作用域内模拟您网域的任意用户。您已准备好代表您网域的用户实例化授权的 Cloud Search API 服务对象。

对 Cloud Search API 服务对象进行实例化

本部分显示如何实例化 Cloud Search API 服务对象，然后授权它使用 OAuth 2.0 和您的服务账号的凭据执行 API 请求，以执行 Google Workspace 网域范围的委派。这些示例从 JSON 格式的私钥文件中读取服务账号的信息。

Java

import java.util.Collections;
import java.io.FileInputStream;
import com.google.api.client.googleapis.auth.oauth2.GoogleCredential;
import com.google.api.client.http.HttpTransport;
import com.google.api.client.json.JsonFactory;
import com.google.api.services.cloudsearch.v1.CloudSearch;
import com.google.api.services.cloudsearch.v1.CloudSearchScopes;
...

/** Path to the Service Account's Private Key file */
private static final String SERVICE_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.
 */
public static CloudSearch getCloudSearchAPIService(String userEmail)
    throws FileNotFoundException, IOException {

  FileInputStream credsFile = new FileInputStream(SERVICE_ACCOUNT_FILE_PATH);

  GoogleCredential init = GoogleCredential.fromStream(credsFile);

  HttpTransport httpTransport = init.getTransport();
  JsonFactory jsonFactory = init.getJsonFactory();

  GoogleCredential creds = new GoogleCredential.Builder()
      .setTransport(httpTransport)
      .setJsonFactory(jsonFactory)
      .setServiceAccountId(init.getServiceAccountId())
      .setServiceAccountPrivateKey(init.getServiceAccountPrivateKey())
      .setServiceAccountScopes(Collections.singleton(CloudSearchScopes.CLOUD_SEARCH_QUERY))
      .setServiceAccountUser(userEmail)
      .build();

  CloudSearch service = new CloudSearch.Builder(httpTransport, jsonFactory, creds).build();

  return service;
}

Python

from google.oauth2 import service_account
from googleapiclient.discovery import build

# Path to the Service Account's Private Key file
SERVICE_ACCOUNT_FILE_PATH = "/path/to/key.json"

def create_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)

    return build("cloudsearch", "v1", credentials=delegated_credentials)