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

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

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

الأهداف

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

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

لتنفيذ هذه الخطوة السريعة، تحتاج إلى ما يلي:

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

لإكمال هذه الخطوات السريعة، عليك أولاً إعداد مشروعك على Cloud.

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

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

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

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

  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 صحة هذا التطبيق.". هذا أمر طبيعي، يُرجى اختيار "متابعة".

يؤدي ذلك إلى وضع الرمز المميّز الناتج في موقع معروف حتى يمكن لـ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)، تحتاج مكتبات البرنامج بمعظم اللغات إلى الحدّ الأدنى من المساعدة أو لا تحتاج إلى أي مساعدة للعثور عليها.

Curl

إنّ أسرع طريقة لاختبار عمل هذا الإجراء هي استخدامه للوصول إلى واجهة برمجة التطبيقات 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

في 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 مكتبات بالعديد من اللغات للسماح لك بإدارة هذه العملية في تطبيقك. يوضّح هذا القسم العملية بلغة Python. تتوفّر أمثلة مماثلة لهذا النوع من الإجراءات بلغات أخرى في مستندات Drive API.

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. يتم تخزين معلومات التفويض في نظام الملفات، لذا لن يُطلب منك التفويض في المرة التالية التي تدخِل فيها رمزًا نموذجيًا.

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