Ephemeral tokens

Shenjat kalimtare janë argumente vërtetimi jetëshkurtër për të hyrë në API Gemini përmes WebSockets . Ato janë krijuar për të rritur sigurinë kur jeni duke u lidhur drejtpërdrejt nga pajisja e një përdoruesi me API-në (një zbatim nga klienti në server ). Ashtu si çelësat standardë API, shenjat kalimtare mund të nxirren nga aplikacionet e klientit si shfletuesit e uebit ose aplikacionet celulare. Por për shkak se shenjat kalimtare skadojnë shpejt dhe mund të kufizohen, ato reduktojnë ndjeshëm rreziqet e sigurisë në një mjedis prodhimi.

Si funksionojnë shenjat kalimtare

Ja se si funksionojnë shenjat kalimtare në një nivel të lartë:

1. Klienti juaj (p.sh. aplikacioni i uebit) vërtetohet me backend-in tuaj.
2. Backend-i juaj kërkon një shenjë kalimtare nga shërbimi i sigurimit të Gemini API.
3. Gemini API lëshon një token jetëshkurtër.
4. Backend-i juaj i dërgon kodin klientit për lidhjet WebSocket në Live API. Ju mund ta bëni këtë duke shkëmbyer çelësin tuaj API me një shenjë kalimtare.
5. Më pas klienti përdor tokenin sikur të ishte një çelës API.

Kjo rrit sigurinë sepse edhe nëse nxirret, token është jetëshkurtër, ndryshe nga një çelës API jetëgjatë i vendosur në anën e klientit. Meqenëse klienti dërgon të dhëna direkt te Binjakët, kjo gjithashtu përmirëson vonesën dhe shmang nevojën e mbështetësve tuaj për të përfaqsuar të dhënat në kohë reale.

Krijo një shenjë kalimtare

Këtu është një shembull i thjeshtuar se si të merrni një shenjë kalimtare nga Binjakët. Si parazgjedhje, do të keni 1 minutë për të nisur sesionet e reja Live API duke përdorur tokenin nga kjo kërkesë ( newSessionExpireTime ) dhe 30 minuta për të dërguar mesazhe mbi atë lidhje ( 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'},
    },
  });

Për kufizimet e vlerës së expireTime , parazgjedhjet dhe specifikat e tjera të fushës, shihni referencën API . Brenda afatit kohor të expireTime , do t'ju duhet sessionResumption për të rilidhur telefonatën çdo 10 minuta (kjo mund të bëhet me të njëjtin kod edhe nëse uses: 1 ).

Është gjithashtu e mundur të bllokohet një shenjë kalimtare në një grup konfigurimesh. Kjo mund të jetë e dobishme për të përmirësuar më tej sigurinë e aplikacionit tuaj dhe për të mbajtur udhëzimet e sistemit në anën e serverit.

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

Ju gjithashtu mund të kyçni një nëngrup fushash, shikoni dokumentacionin e SDK-së për më shumë informacion.

Lidhu me Live API me një shenjë kalimtare

Pasi të keni një shenjë kalimtare, ju e përdorni atë sikur të ishte një çelës API (por mbani mend, funksionon vetëm për API-në e drejtpërdrejtë dhe vetëm me versionin v1alpha të API-së).

Vini re se përdorimi i shenjave kalimtare shton vlerë vetëm kur vendoset aplikacione që ndjekin qasjen e zbatimit nga klienti në server .

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();

Shikoni Filloni me API-në e drejtpërdrejtë për më shumë shembuj.

Praktikat më të mira

• Vendosni një kohëzgjatje të shkurtër skadimi duke përdorur parametrin expire_time .
• Shenjat skadojnë, duke kërkuar rifillimin e procesit të sigurimit.
• Verifikoni vërtetimin e sigurt për backend-in tuaj. Shenjat kalimtar do të jenë po aq të sigurt sa metoda juaj e vërtetimit të backend.
• Në përgjithësi, shmangni përdorimin e shenjave kalimtare për lidhjet backend-to-Gemini, pasi kjo rrugë zakonisht konsiderohet e sigurt.

Kufizimet

Shenjat kalimtare janë të përputhshme vetëm me Live API për momentin.

Çfarë është më pas

• Lexoni referencën Live API për shenjat kalimtare për më shumë informacion.