إجراء تفويض على مستوى نطاق Google Workspace

تتطلّب واجهة برمجة التطبيقات Cloud Search Query API تفويض طلبات البيانات من واجهة برمجة التطبيقات باستخدام بيانات اعتماد OAuth التي يملكها مستخدم مرخّص في نطاقك. بشكلٍ تلقائي، لا يمكن استخدام حسابات الخدمة التي يتم استخدامها للوصول إلى واجهات برمجة تطبيقات الفهرسة والضبط لطلبات البحث من واجهة برمجة التطبيقات لأنّها ليست حسابات مستخدمين في النطاق لديهم تراخيص Cloud Search أو Google Workspace. إذا كنت تريد استخدام حساب خدمة عند مصادقة طلبات بيانات من واجهة برمجة التطبيقات لطلبات البحث، يمكن لمشرف النطاق منح الحساب إذن الوصول على مستوى النطاق إلى بيانات المستخدمين، ويُعرف ذلك باسم تفويض المرجع على مستوى النطاق. يمكن لحساب الخدمة الذي لديه سلطة مفوَّضة انتحال هوية أي مستخدم، بما في ذلك المستخدمين الذين يمكنهم الوصول إلى Cloud Search.

إنشاء حساب الخدمة وبيانات الاعتماد

إذا لم تكن لديك بيانات اعتماد حساب الخدمة بعد، راجِع مقالة إنشاء بيانات اعتماد حساب الخدمة.

تفويض الإذن على مستوى النطاق لحساب الخدمة

للوصول إلى بيانات المستخدمين في نطاق Google Workspace، يجب أن يمنح مشرف متميّز للّنطاق إذن الوصول إلى حساب الخدمة الذي أنشأته. لمزيد من المعلومات حول التفويض على مستوى النطاق، يُرجى الاطّلاع على مقالة التحكّم في الوصول إلى Google Workspace API من خلال التفويض على مستوى النطاق.

لتفويض تفويض على مستوى النطاق لحساب خدمة:

1. من وحدة تحكُّم المشرف في نطاقك، انتقِل إلى القائمة الرئيسية > الأمان > التحكّم في البيانات والوصول > عناصر التحكّم في واجهة برمجة التطبيقات.

2. في لوحة التفويض على مستوى النطاق، اختَر إدارة التفويض على مستوى النطاق.

3. انقر على إضافة نطاق جديد.

4. في الحقل معرّف العميل، أدخِل معرّف العميل الذي تم الحصول عليه من خطوات إنشاء حساب الخدمة أعلاه.

5. في حقل نطاقات OAuth، أدخِل قائمة مفصولة بفواصل بالنطاقات المطلوبة لتطبيقك. استخدِم النطاق https://www.googleapis.com/auth/cloud_search.query لتطبيقات البحث باستخدام Query API.

6. انقر على تفويض.

أصبح لحساب الخدمة الآن إذن وصول على مستوى النطاق إلى واجهة برمجة التطبيقات Cloud Search Query API، ويمكنه انتحال هوية أي مستخدم في نطاقك في هذا النطاق. أنت الآن مستعد لإنشاء مثيل لكائن خدمة Cloud Search API مفوَّض نيابةً عن مستخدمي نطاقك.

ملاحظة: للوصول إلى Query API، يجب أن تنتحل خدمتك هوية مستخدم لديه إذن بالوصول إلى Cloud Search. بالإضافة إلى ذلك، يجب أن يكون المستخدم قد سجّل الدخول مرة واحدة على الأقل وقبل بنود خدمة Google Workspace. ستعرِض Query API النتائج التي تتضمّن قوائم التحكّم بالوصول وفقًا لأذونات المستخدم الذي تم انتحال هويته.

إنشاء مثيل لعنصر خدمة Cloud Search API

يوضّح هذا القسم كيفية إنشاء مثيل لعنصر خدمة Cloud Search API ثم تفويضه لتقديم طلبات إلى واجهة برمجة التطبيقات باستخدام OAuth 2.0 وبيانات اعتماد حساب الخدمة لتنفيذ التفويض على مستوى نطاق 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)