אסימונים זמניים הם אסימוני אימות לטווח קצר שמאפשרים לגשת ל-Gemini API דרך WebSockets. הם נועדו לשפר את האבטחה כשמתחברים ישירות מהמכשיר של המשתמש ל-API (הטמעה מסוג לקוח-שרת). כמו מפתחות API רגילים, אפשר לחלץ אסימונים זמניים מאפליקציות בצד הלקוח, כמו דפדפני אינטרנט או אפליקציות לנייד. עם זאת, מכיוון שפג התוקף של אסימונים זמניים קצר ואפשר להגביל אותם, הם מפחיתים באופן משמעותי את סיכוני האבטחה בסביבת הייצור.
איך פועלים אסימונים זמניים
כך פועלים אסימונים זמניים ברמה גבוהה:
- הלקוח (למשל אפליקציית אינטרנט) מבצע אימות מול הקצה העורפי.
- הקצה העורפי מבקש אסימון זמני משירות הקצאת המשאבים של Gemini API.
- Gemini API מנפיק אסימון לטווח קצר.
- הקצה העורפי שולח את האסימון ללקוח לחיבורי WebSocket ל-Live API. כדי לעשות זאת, מחליפים את מפתח ה-API באסימון חולף.
- לאחר מכן, הלקוח משתמש באסימון כאילו הוא מפתח API.
כך אפשר לשפר את האבטחה, כי גם אם האסימון מחובר, הוא לטווח קצר, בניגוד למפתח API לטווח ארוך שנפרס בצד הלקוח. מכיוון שהלקוח שולח נתונים ישירות ל-Gemini, כך גם משתפרת זמן האחזור, ולא צריך להשתמש בשרת proxy כדי להעביר את הנתונים בזמן אמת לקצה העורפי.
יצירת אסימון חולף
הנה דוגמה פשוטה לאופן שבו מקבלים אסימון חולף מ-Gemini.
כברירת מחדל, תהיה לכם דקה אחת כדי להתחיל סשנים חדשים של API בזמן אמת באמצעות האסימון מהבקשה הזו (newSessionExpireTime
), ו-30 דקות כדי לשלוח הודעות דרך החיבור הזה (expireTime
).
Python
import datetime
now = datetime.datetime.now(tz=datetime.timezone.utc)
client = genai.Client(
http_options={'api_version': 'v1alpha',}
)
token = client.auth_tokens.create(
config = {
'uses': 1, # The ephemeral token can only be used to start a single session
'expire_time': now + datetime.timedelta(minutes=30), # Default is 30 minutes in the future
# 'expire_time': '2025-05-17T00:00:00Z', # Accepts isoformat.
'new_session_expire_time': now + datetime.timedelta(minutes=1), # Default 1 minute in the future
'http_options': {'api_version': 'v1alpha'},
}
)
# You'll need to pass the value under token.name back to your client to use it
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token: AuthToken = await client.authTokens.create({
config: {
uses: 1, // The default
expireTime: expireTime // Default is 30 mins
newSessionExpireTime: new Date(Date.now() + (1 * 60 * 1000)), // Default 1 minute in the future
httpOptions: {apiVersion: 'v1alpha'},
},
});
למידע על אילוצים, ברירת מחדל ומפרטי שדות אחרים של הערך expireTime
, ראו הפניית API.
במסגרת מסגרת הזמן expireTime
, תצטרכו להשתמש ב-sessionResumption
כדי לחדש את החיבור לשיחה כל 10 דקות (אפשר לעשות זאת עם אותו אסימון גם אם uses: 1
).
אפשר גם לנעול אסימון חולף לקבוצת הגדרות. כדאי להשתמש באפשרות הזו כדי לשפר את האבטחה של האפליקציה ולשמור את הוראות המערכת בצד השרת.
Python
client = genai.Client(
http_options={'api_version': 'v1alpha',}
)
token = client.auth_tokens.create(
config = {
'uses': 1,
'live_connect_constraints': {
'model': 'gemini-2.0-flash-live-001',
'config': {
'session_resumption':{},
'temperature':0.7,
'response_modalities':['TEXT']
}
},
'http_options': {'api_version': 'v1alpha'},
}
)
# You'll need to pass the value under token.name back to your client to use it
JavaScript
import { GoogleGenAI } from "@google/genai";
const client = new GoogleGenAI({});
const expireTime = new Date(Date.now() + 30 * 60 * 1000).toISOString();
const token = await client.authTokens.create({
config: {
uses: 1, // The default
expireTime: expireTime,
liveConnectConstraints: {
model: 'gemini-2.0-flash-live-001',
config: {
sessionResumption: {},
temperature: 0.7,
responseModalities: ['TEXT']
}
},
httpOptions: {
apiVersion: 'v1alpha'
}
}
});
// You'll need to pass the value under token.name back to your client to use it
אפשר גם לנעול קבוצת משנה של שדות. מידע נוסף זמין במסמכי התיעוד של ה-SDK.
חיבור ל-Live API באמצעות אסימון חולף
הנה דוגמה להתחברות ל-Live API באמצעות אסימון חולף. חשוב לזכור ששימוש באסימונים זמניים מועיל רק כשפורסים אפליקציות לפי הגישה של הטמעה מלקוח לשרת.
JavaScript
import { GoogleGenAI, Modality } from '@google/genai';
// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({});
const model = 'gemini-2.0-flash-live-001';
const config = { responseModalities: [Modality.TEXT] };
async function main() {
const session = await ai.live.connect({
model: model,
config: config,
callbacks: { ... },
});
// Send content...
session.close();
}
main();
דוגמאות נוספות מפורטות במאמר תחילת השימוש ב-Live API.
שיטות מומלצות
- מגדירים משך תפוגה קצר באמצעות הפרמטר
expire_time
. - תוקף האסימונים פג, וצריך להתחיל מחדש את תהליך ההקצאה.
- אימות מאובטח לקצה העורפי שלכם. האבטחה של אסימונים זמניים תהיה טובה רק כמו שיטת האימות בקצה העורפי.
- באופן כללי, מומלץ להימנע משימוש באסימונים זמניים לחיבורים לקצה העורפי של Gemini, כי בדרך כלל הנתיב הזה נחשב מאובטח.
מגבלות
בשלב זה, טוקנים זמניים תואמים רק ל-Live API.
המאמרים הבאים
- למידע נוסף, אפשר לעיין במאמר העזרה בנושא אסימונים זמניים ב-Live API.