Ephemeral tokens

الرموز المميزة المؤقتة هي رموز مميزة قصيرة الأمد للمصادقة تتيح الوصول إلى Gemini API من خلال WebSockets. وهي مصمَّمة لتعزيز الأمان عند الربط مباشرةً من جهاز المستخدم بواجهة برمجة التطبيقات (تنفيذ من العميل إلى الخادم). مثل مفاتيح واجهة برمجة التطبيقات العادية، يمكن استخراج الرموز المميزة المؤقتة من التطبيقات من جهة العميل، مثل متصفّحات الويب أو تطبيقات الأجهزة الجوّالة. ولكن بما أنّ الرموز المميزة المؤقتة تنتهي صلاحيتها بسرعة ويمكن حظرها، فإنّها تقلّل بشكل كبير من مخاطر الأمان في بيئة الإنتاج.

طريقة عمل الرموز المميزة المؤقتة

في ما يلي طريقة عمل الرموز المميزة المؤقتة بشكل عام:

1. يتم مصادقة العميل (مثل تطبيق الويب) مع الخلفية.
2. يطلب الخلفية رمزًا مميّزًا مؤقتًا من خدمة التزويد في Gemini API.
3. يصدر Gemini API رمزًا مميزًا قصير الأجل.
4. يرسل الخلفية الرمز المميّز إلى العميل لعمليات ربط WebSocket بواجهة Live API. يمكنك إجراء ذلك عن طريق استبدال مفتاح واجهة برمجة التطبيقات برمز مميّز مؤقت.
5. يستخدم العميل بعد ذلك الرمز المميز كما لو كان مفتاح واجهة برمجة تطبيقات.

ويؤدي ذلك إلى تعزيز الأمان لأنّ الرمز المميّز يكون صالحًا لفترة قصيرة حتى إذا تم استخراجه، على عكس مفتاح واجهة برمجة التطبيقات الذي يكون صالحًا لفترة طويلة ويتم نشره من جهة العميل. بما أنّ العميل يرسل البيانات مباشرةً إلى Gemini، يؤدي ذلك أيضًا إلى تحسين وقت الاستجابة وتجنُّب الحاجة إلى أن تعمل الأنظمة الخلفية كوكيل للبيانات في الوقت الفعلي.

إنشاء رمز مميّز مؤقت

في ما يلي مثال مبسط على كيفية الحصول على رمز مميّز مؤقت من Gemini. بشكلٍ تلقائي، سيكون لديك دقيقة واحدة لبدء جلسات جديدة في Live API باستخدام الرمز المميّز من هذا الطلب (newSessionExpireTime)، و30 دقيقة لإرسال الرسائل عبر هذا الاتصال (expireTime).

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

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 والإعدادات التلقائية ومواصفات الحقول الأخرى، يُرجى الرجوع إلى مرجع واجهة برمجة التطبيقات. خلال الإطار الزمني expireTime، عليك sessionResumption إعادة الاتصال كل 10 دقائق (يمكن إجراء ذلك باستخدام الرمز المميز نفسه حتى إذا كان uses: 1).

من الممكن أيضًا حصر استخدام الرمز المميز المؤقت بمجموعة من الإعدادات. قد يكون ذلك مفيدًا لزيادة تحسين أمان تطبيقك والحفاظ على تعليمات نظامك على الخادم.

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

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 باستخدام رمز مميز مؤقت

بعد الحصول على رمز مميّز مؤقت، يمكنك استخدامه كما لو كان مفتاح واجهة برمجة تطبيقات (ولكن تذكَّر أنّه لا يعمل إلا مع واجهة برمجة التطبيقات المباشرة، ومع الإصدار v1alpha من واجهة برمجة التطبيقات فقط).

يُرجى العِلم أنّ استخدام الرموز المميزة المؤقتة لا يضيف قيمة إلا عند نشر التطبيقات التي تتّبع نهج التنفيذ من العميل إلى الخادم.

import { GoogleGenAI, Modality } from '@google/genai';

// Use the token generated in the "Create an ephemeral token" section here
const ai = new GoogleGenAI({
  apiKey: token.name
});
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 حول الرموز المميزة المؤقتة للحصول على مزيد من المعلومات.