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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

إنشاء مثيل لكائن خدمة واجهة برمجة تطبيقات Cloud Search

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