المصادقة باستخدام التشغيل السريع لبروتوكول 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 إلى بيانات اعتماد قابلة للاستخدام، يُرجى إدخال موضع الأمر gcloud auth application-default login الوسيطة --client-id-file.

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

في بايثون، من المفترض أن تعثر مكتبات العميل عليها تلقائيًا:

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

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