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

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

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

الأهداف

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

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

لتنفيذ هذا التشغيل السريع، يجب توفُّر ما يلي:

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

لإكمال هذا الدليل السريع، عليك أولاً إعداد مشروعك على السحابة الإلكترونية.

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

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

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

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

  1. في وحدة تحكّم Google Cloud، انتقِل إلى القائمة > > نظرة عامة.

    الانتقال إلى

  2. أكمِل نموذج إعدادات المشروع واضبط نوع المستخدم على خارجي في قسم الجمهور.

  3. أكمِل بقية النموذج، واقبل بنود سياسة بيانات المستخدِم، ثم انقر على إنشاء.

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

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

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

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

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

  1. في وحدة تحكّم Google Cloud، انتقِل إلى القائمة > > العملاء.

    الانتقال إلى "بيانات الاعتماد"

  2. انقر على إنشاء عميل.

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

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

  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'

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

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

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