Ephemeral tokens

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

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

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

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-live-2.5-flash-preview';
const config = { responseModalities: [Modality.AUDIO] };

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 بشأن الرموز المميزة المؤقتة للحصول على مزيد من المعلومات.