אימות באמצעות מדריך למתחילים של OAuth

הדרך הקלה ביותר לבצע אימות ל-Gemini API היא להגדיר מפתח API, כפי שמתואר במאמר תחילת העבודה עם Gemini API. אם אתם צריכים אמצעי בקרת גישה מחמירים יותר, תוכלו להשתמש ב-OAuth במקום זאת. המדריך הזה יעזור לכם להגדיר אימות באמצעות OAuth.

במדריך הזה נעשה שימוש בגישת אימות פשוטה שמתאימה לסביבת בדיקה. בסביבת ייצור מומלץ לקרוא על אימות והרשאה לפני שבוחרים את פרטי הכניסה שמתאימים לאפליקציה.

מטרות

  • הגדרת פרויקט בענן ל-OAuth
  • הגדרת application-default-credentials
  • ניהול פרטי הכניסה בתוכנית במקום להשתמש ב-gcloud auth

דרישות מוקדמות

כדי להריץ את המדריך למתחילים הזה, צריך:

הגדרת פרויקט בענן

כדי להשלים את המדריך למתחילים הזה, קודם צריך להגדיר את פרויקט Cloud.

1. הפעלת ה-API

לפני שמשתמשים ב-Google APIs, צריך להפעיל אותם בפרויקט ב-Google Cloud.

  • במסוף Google Cloud, מפעילים את Google Generative Language API.

    להפעלת ה-API

2. הגדרת מסך ההסכמה של OAuth

בשלב הבא מגדירים את מסך ההסכמה של OAuth בפרויקט ומוסיפים את עצמכם כמשתמשי בדיקה. אם כבר השלמתם את השלב הזה בפרויקט ב-Cloud, דלגו לחלק הבא.

  1. במסוף Google Cloud, נכנסים אל תפריט > APIs & Services > OAuth screen consent.

    כניסה למסך ההסכמה של OAuth

  2. בוחרים את סוג המשתמש חיצוני לאפליקציה ולוחצים על Create.

  3. ממלאים את טופס הרישום של האפליקציה (אפשר להשאיר את רוב השדות ריקים) ולוחצים על שמירה והמשך.

  4. בשלב הזה אפשר לדלג על הוספת היקפי הרשאות וללחוץ על שמירה והמשך. בעתיד, כשיוצרים אפליקציה לשימוש מחוץ לארגון ב-Google Workspace, צריך להוסיף ולאמת את היקפי ההרשאה הנדרשים לאפליקציה.

  5. מוסיפים משתמשי בדיקה:

    1. בקטע Test users, לוחצים על Add users.
    2. מזינים את כתובת האימייל שלכם ואת כתובות האימייל של כל משתמשי הבדיקה המורשים האחרים, ולוחצים על Save and Continue (שמירה והמשך).

  6. בודקים את סיכום רישום האפליקציה. כדי לבצע שינויים, לוחצים על עריכה. אם הרשמת האפליקציה נראית תקינה, לוחצים על Back to Dashboard (חזרה למרכז הבקרה).

3. אישור פרטי כניסה לאפליקציה בשולחן העבודה

כדי לבצע אימות כמשתמש קצה ולגשת לנתוני המשתמשים באפליקציה, צריך ליצור מזהה לקוח אחד או יותר ב-OAuth 2.0. מזהה לקוח משמש לזיהוי אפליקציה אחת בשרתי OAuth של Google. אם האפליקציה פועלת בכמה פלטפורמות, צריך ליצור מזהה לקוח נפרד לכל פלטפורמה.

  1. נכנסים למסוף Google Cloud, לוחצים על תפריט > APIs & Services > Credentials.

    כניסה לדף Credentials

  2. לוחצים על Create Credentials (יצירת פרטי כניסה) > OAuth client ID (מזהה לקוח OAuth).

  3. לוחצים על Application type (סוג האפליקציה) > Desktop app (אפליקציה למחשב).

  4. בשדה Name, מקלידים שם לפרטי הכניסה. השם הזה מוצג רק במסוף Google Cloud.

  5. לוחצים על יצירה. יופיע המסך של לקוח OAuth שנוצר, שבו יוצגו מזהה הלקוח וסוד הלקוח החדשים.

  6. לוחצים על אישור. פרטי הכניסה החדשים שיצרתם יופיעו בקטע מזהי לקוח של OAuth 2.0.

  7. לוחצים על לחצן ההורדה כדי לשמור את קובץ ה-JSON. הוא יישמר בתור client_secret_<identifier>.json, ותצטרכו לשנות את השם שלו ל-client_secret.json ולהעביר אותו לספריית העבודה.

הגדרת Application Default Credentials

כדי להמיר את הקובץ 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 hasn't verified this app". זוהי תופעה רגילה. בוחרים באפשרות 'המשך'.

כך האסימון שנוצר ממוקם במיקום ידוע, כך שאפשר לגשת אליו באמצעות 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

הדרך המהירה ביותר לבדוק אם זה עובד היא להשתמש בו כדי לגשת ל-API של 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. פרטי ההרשאה מאוחסנים במערכת הקבצים, כך שבפעם הבאה שתפעילו את הקוד לדוגמה לא תתבקשו להעניק הרשאה.

סיימתם להגדיר את האימות.