المصادقة باستخدام التشغيل السريع لبروتوكول OAuth

تتيح لك واجهة برمجة التطبيقات Gemini API استرداد البيانات الدلالية. بما أنّها بياناتك، يحتاج هذا الإجراء إلى عناصر تحكّم أكثر صرامة في الوصول إلى البيانات مقارنةً بمفاتيح واجهة برمجة التطبيقات.

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

الأهداف

  • إعداد مشروعك على السحابة الإلكترونية لبروتوكول OAuth
  • ضبط بيانات الاعتماد التلقائية للتطبيق
  • إدارة بيانات الاعتماد في برنامجك بدلاً من استخدام gcloud auth

المتطلبات الأساسية

لتشغيل هذه الأداة السريعة، تحتاج إلى ما يلي:

إعداد مشروعك على السحابة الإلكترونية

لإكمال عملية البدء السريع هذه، عليك أولاً إعداد مشروعك على Google Cloud.

1- تفعيل واجهة برمجة التطبيقات

قبل استخدام Google APIs، عليك تفعيلها في مشروع على Google Cloud.

2. ضبط شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

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

  1. في وحدة تحكُّم Google Cloud، انتقِل إلى القائمة > واجهات برمجة التطبيقات والخدمات > شاشة موافقة OAuth.

    الانتقال إلى شاشة طلب الموافقة المتعلّقة ببروتوكول OAuth

  2. اختَر نوع المستخدم خارجي لتطبيقك، ثم انقر على إنشاء.

  3. أكمل نموذج تسجيل التطبيق (يمكنك ترك معظم الحقول فارغة)، ثم انقر على حفظ ومتابعة.

  4. في الوقت الحالي، يمكنك تخطّي إضافة النطاقات والنقر على حفظ ومتابعة. في المستقبل، عند إنشاء تطبيق للاستخدام خارج مؤسسة Google Workspace، عليك إضافة نطاقات التفويض التي يتطلبها تطبيقك والتحقّق منها.

  5. إضافة مستخدمين تجريبيين:

    1. ضمن المستخدمون التجريبيون، انقر على إضافة مستخدمين.
    2. أدخِل عنوان بريدك الإلكتروني وأي مستخدمين مختبِرين معتمَدين آخرين، ثم انقر على حفظ ومتابعة.

  6. مراجعة ملخص تسجيل التطبيق لإجراء تغييرات، انقر على تعديل. إذا كان تسجيل التطبيق يبدو على ما يرام، انقر على الرجوع إلى لوحة البيانات.

3- تفويض بيانات الاعتماد لتطبيق سطح المكتب

للمصادقة بصفتك مستخدمًا نهائيًا والوصول إلى بيانات المستخدم في تطبيقك، عليك إنشاء معرِّف عميل OAuth 2.0 واحد أو أكثر. يتم استخدام معرّف العميل لتحديد تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على أنظمة أساسية متعددة، يجب عليك إنشاء معرّف عميل منفصل لكل نظام أساسي.

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

    الانتقال إلى صفحة "بيانات الاعتماد"

  2. انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.

  3. انقر على نوع التطبيق > تطبيق الكمبيوتر المكتبي.

  4. في حقل الاسم، اكتب اسمًا لبيانات الاعتماد. لا يظهر هذا الاسم إلا في وحدة تحكم Google Cloud.

  5. انقر على إنشاء. تظهر الشاشة التي أنشأها عميل OAuth وتعرض معرّف العميل وسر العميل الجديد.

  6. انقر على موافق. تظهر بيانات الاعتماد التي تم إنشاؤها حديثًا ضمن معرّفات عميل OAuth 2.0.

  7. انقر على زر التنزيل لحفظ ملف JSON. سيتم حفظه باسم client_secret_<identifier>.json وإعادة تسميته إلى client_secret.json ونقله إلى دليل العمل.

إعداد بيانات الاعتماد التلقائية للتطبيق

لتحويل ملف client_secret.json إلى بيانات اعتماد قابلة للاستخدام، ضَع موقعه على وسيطة --client-id-file الخاصة بالأمر gcloud auth application-default login.

gcloud auth application-default login \
    --client-id-file=client_secret.json \
    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'

يؤدي الإعداد المبسَّط للمشروع في هذا البرنامج التعليمي إلى تشغيل مربع حوار "لم تتحقق Google من هذا التطبيق". هذا أمر طبيعي، لذا اختَر "continue".

يضع هذا الرمز الرمز المميّز الناتج في مكان معروف، بحيث يمكن الوصول إليه من خلال gcloud أو مكتبات العميل.

gcloud auth application-default login 

    --no-browser
    --client-id-file=client_secret.json 

    --scopes='https://www.googleapis.com/auth/cloud-platform,https://www.googleapis.com/auth/generative-language.retriever'

بعد ضبط بيانات الاعتماد التلقائية للتطبيق (ACD)، تحتاج مكتبات البرامج بمعظم اللغات إلى الحد الأدنى من المساعدة للعثور عليها أو ألّا تحتاج إلى أي مساعدة.

تمرين تجفيف

وأسرع طريقة لاختبار مدى نجاح هذا الأمر هي استخدامه للوصول إلى واجهة برمجة تطبيقات REST باستخدام curl:

access_token=$(gcloud auth application-default print-access-token)
project_id=<MY PROJECT ID>

curl -X GET https://generativelanguage.googleapis.com/v1/models \
    -H 'Content-Type: application/json' \
    -H "Authorization: Bearer ${access_token}" \
    -H "x-goog-user-project: ${project_id}" | grep '"name"'

Python

في لغة بايثون، يُفترض أن تجد مكتبات العميل هذه الملفات تلقائيًا:

pip install google-generativeai

في ما يلي الحد الأدنى من النص البرمجي لاختباره:

import google.generativeai as genai

print('Available base models:', [m.name for m in genai.list_models()])

الخطوات التالية

إذا كان ذلك مفيدًا، فأنت على استعداد لتجربة الاسترجاع الدلالي للبيانات النصية.

إدارة بيانات الاعتماد بنفسك [Python]

في كثير من الحالات، لن يتوفر الأمر gcloud لإنشاء رمز الوصول من معرف العميل (client_secret.json). توفر Google مكتبات بلغات متعددة تتيح لك إدارة هذه العملية داخل تطبيقك. يوضح هذا القسم عملية الوصول في بايثون. هناك أمثلة مماثلة لهذا النوع من الإجراءات، للغات الأخرى، والمتاحة في وثائق واجهة برمجة تطبيقات Drive

1- تثبيت المكتبات اللازمة

ثبِّت مكتبة برامج Google للغة Python، ومكتبة برامج Gemini.

pip install --upgrade -q google-api-python-client google-auth-httplib2 google-auth-oauthlib

pip install google-generativeai

2. كتابة مدير بيانات الاعتماد

لتقليل عدد المرات التي يتعين عليك فيها النقر على شاشات التفويض، يمكنك إنشاء ملف باسم load_creds.py في دليل العمل لتخزين ملف token.json مؤقتًا يمكن إعادة استخدامه لاحقًا أو إعادة تحميله إذا انتهت صلاحيته.

ابدأ بالرمز التالي لتحويل ملف client_secret.json إلى رمز مميّز قابل للاستخدام مع genai.configure:

import os.path

from google.auth.transport.requests import Request
from google.oauth2.credentials import Credentials
from google_auth_oauthlib.flow import InstalledAppFlow

SCOPES = ['https://www.googleapis.com/auth/generative-language.retriever']

def load_creds():
    """Converts `client_secret.json` to a credential object.

    This function caches the generated tokens to minimize the use of the
    consent screen.
    """
    creds = None
    # The file token.json stores the user's access and refresh tokens, and is
    # created automatically when the authorization flow completes for the first
    # time.
    if os.path.exists('token.json'):
        creds = Credentials.from_authorized_user_file('token.json', SCOPES)
    # If there are no (valid) credentials available, let the user log in.
    if not creds or not creds.valid:
        if creds and creds.expired and creds.refresh_token:
            creds.refresh(Request())
        else:
            flow = InstalledAppFlow.from_client_secrets_file(
                'client_secret.json', SCOPES)
            creds = flow.run_local_server(port=0)
        # Save the credentials for the next run
        with open('token.json', 'w') as token:
            token.write(creds.to_json())
    return creds

3- كتابة البرنامج

يمكنك الآن إنشاء script.py الخاص بك:

import pprint
import google.generativeai as genai
from load_creds import load_creds

creds = load_creds()

genai.configure(credentials=creds)

print()
print('Available base models:', [m.name for m in genai.list_models()])

4. تشغيل البرنامج

في دليل العمل، شغِّل النموذج:

python script.py

في المرة الأولى التي يتم فيها تشغيل النص البرمجي، يتم فتح نافذة متصفح ويطالبك بمنح إذن الوصول.

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

  2. يتم تخزين معلومات التفويض في نظام الملفات، لذا في المرة القادمة التي تقوم فيها بتشغيل نموذج التعليمات البرمجية، لن تتم مطالبتك بالتفويض.

تم إعداد المصادقة بنجاح.