Obtenir des informations sur un cache de contexte

Vous pouvez connaître la date de création d'un cache de contexte, la date de sa dernière mise à jour et son délai d'expiration. Pour obtenir des informations sur chaque cache de contexte associé à un projet Google Cloud , y compris leurs ID de cache, utilisez la commande permettant de lister les caches de contexte. Si vous connaissez l'ID d'un cache de contexte, vous pouvez obtenir des informations sur ce cache de contexte uniquement.

Obtenir la liste des caches de contexte

Pour obtenir la liste des caches de contexte associés à un projet Google Cloud , vous avez besoin de l'ID de votre projet Google Cloud et de la région dans laquelle vous l'avez créé. L'exemple suivant montre comment obtenir la liste des caches de contexte pour un projet Google Cloud .

Python

Installer

pip install --upgrade google-genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI :

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

from google import genai
from google.genai.types import HttpOptions

client = genai.Client(http_options=HttpOptions(api_version="v1"))

content_cache_list = client.caches.list()

# Access individual properties of a ContentCache object(s)
for content_cache in content_cache_list:
    print(f"Cache `{content_cache.name}` for model `{content_cache.model}`")
    print(f"Last updated at: {content_cache.update_time}")
    print(f"Expires at: {content_cache.expire_time}")

# Example response:
# * Cache `projects/111111111111/locations/.../cachedContents/1111111111111111111` for
#       model `projects/111111111111/locations/.../publishers/google/models/gemini-XXX-pro-XXX`
# * Last updated at: 2025-02-13 14:46:42.620490+00:00
# * CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167, text_count=153, total_token_count=43130, video_duration_seconds=None)
# ...

Go

Découvrez comment installer ou mettre à jour le Go.

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI :

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"time"

	"google.golang.org/genai"
)

// listContentCache shows how to retrieve details about cached content.
func listContentCache(w io.Writer) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	// Retrieve cached content metadata
	cache, err := client.Caches.List(ctx, &genai.ListCachedContentsConfig{
		HTTPOptions: &genai.HTTPOptions{
			Headers:    http.Header{"X-Custom-Header": []string{"example"}},
			APIVersion: "v1",
		},
	})
	if err != nil {
		return fmt.Errorf("failed to get content cache: %w", err)
	}

	// Print basic info about the cached content
	fmt.Fprintf(w, "Cache name: %s\n", cache.Name)
	fmt.Fprintf(w, "Display name: %s\n", cache.Items[0].DisplayName)
	fmt.Fprintf(w, "Model: %s\n", cache.Items[0].Model)
	fmt.Fprintf(w, "Create time: %s\n", cache.Items[0].CreateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Update time: %s\n", cache.Items[0].UpdateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Expire time: %s (in %s)\n", cache.Items[0].ExpireTime.Format(time.RFC3339), time.Until(cache.Items[0].ExpireTime).Round(time.Second))

	if cache.Items[0].UsageMetadata != nil {
		fmt.Fprintf(w, "Usage metadata: %+v\n", cache.Items[0].UsageMetadata)
	}

	// Example response:
	// Cache name: projects/111111111111/locations/us-central1/cachedContents/1234567890123456789
	// Display name: product_recommendations_prompt
	// Model: models/gemini-2.5-flash
	// Create time: 2025-04-08T02:15:23Z
	// Update time: 2025-04-08T03:05:11Z
	// Expire time: 2025-04-20T03:05:11Z (in 167h59m59s)
	// Usage metadata: &{AudioDurationSeconds:0 ImageCount:167 TextCount:153 TotalTokenCount:43124 VideoDurationSeconds:0}

	return nil
}

Java

Découvrez comment installer ou mettre à jour le Java.

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI :

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

import com.google.genai.Client;
import com.google.genai.types.CachedContent;
import com.google.genai.types.HttpOptions;
import com.google.genai.types.ListCachedContentsConfig;

public class ContentCacheList {

  public static void main(String[] args) {
    contentCacheList();
  }

  // Lists all cached contents
  public static void contentCacheList() {
    // Initialize client that will be used to send requests. This client only needs to be created
    // once, and can be reused for multiple requests.
    try (Client client =
        Client.builder()
            .location("global")
            .vertexAI(true)
            .httpOptions(HttpOptions.builder().apiVersion("v1").build())
            .build()) {

      for (CachedContent content : client.caches.list(ListCachedContentsConfig.builder().build())) {
        content.name().ifPresent(name -> System.out.println("Name: " + name));
        content.model().ifPresent(model -> System.out.println("Model: " + model));
        content.updateTime().ifPresent(time -> System.out.println("Last updated at: " + time));
        content.expireTime().ifPresent(time -> System.out.println("Expires at: " + time));
      }
      // Example response:
      // Name: projects/111111111111/locations/global/cachedContents/1111111111111111111
      // Model:
      // projects/111111111111/locations/global/publishers/google/models/gemini-2.5-flash
      // Last updated at: 2025-07-28T21:54:19.125825Z
      // Expires at: 2025-08-04T21:54:18.328233500Z
      // ...
    }
  }
}

Node.js

Installer

npm install @google/genai

Pour en savoir plus, consultez la documentation de référence du SDK.

Définissez des variables d'environnement pour utiliser le SDK Google Gen AI avec Vertex AI :

# Replace the `GOOGLE_CLOUD_PROJECT` and `GOOGLE_CLOUD_LOCATION` values
# with appropriate values for your project.
export GOOGLE_CLOUD_PROJECT=GOOGLE_CLOUD_PROJECT
export GOOGLE_CLOUD_LOCATION=global
export GOOGLE_GENAI_USE_ENTERPRISE=True

const {GoogleGenAI} = require('@google/genai');

const GOOGLE_CLOUD_PROJECT = process.env.GOOGLE_CLOUD_PROJECT;
const GOOGLE_CLOUD_LOCATION = process.env.GOOGLE_CLOUD_LOCATION || 'global';
async function listContentCaches(
  projectId = GOOGLE_CLOUD_PROJECT,
  location = GOOGLE_CLOUD_LOCATION
) {
  const client = new GoogleGenAI({
    vertexai: true,
    project: projectId,
    location: location,
    httpOptions: {
      apiVersion: 'v1',
    },
  });

  const contentCacheList = await client.caches.list();

  // Access individual properties of a ContentCache object(s)
  const contentCacheNames = [];
  for (const contentCache of contentCacheList.pageInternal) {
    console.log(
      `Cache \`${contentCache.name}\` for model \`${contentCache.model}\``
    );
    console.log(`Last updated at: ${contentCache.updateTime}`);
    console.log(`Expires at: ${contentCache.expireTime}`);
    contentCacheNames.push(contentCache.name);
  }
  console.log(contentCacheNames);

  // Example response:
  //  * Cache `projects/111111111111/locations/us-central1/cachedContents/1111111111111111111` for
  //  model `projects/111111111111/locations/us-central1/publishers/google/models/gemini-XXX-pro-XXX`
  //  * Last updated at: 2025-02-13 14:46:42.620490+00:00
  //  * CachedContentUsageMetadata(audio_duration_seconds=None, image_count=167, text_count=153, total_token_count=43130, video_duration_seconds=None)
  // ...

  return contentCacheNames;
}

REST

L'exemple suivant montre comment utiliser REST pour lister les caches de contexte associés à un projet Google Cloud en envoyant une demande GET au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• PROJECT_ID : votre [ID du projet](/resource-manager/docs/creating-managing-projects#identifiers). .
• LOCATION : région dans laquelle les requêtes de création de caches de contexte ont été traitées

Méthode HTTP et URL :

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents"

PowerShell

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

Réponse

{
  "cachedContents": [
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_1",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-3.5-flash",
      "createTime": "2024-05-31T19:04:35.380412Z",
      "updateTime": "2024-05-31T19:04:35.380412Z",
      "expireTime": "2024-05-31T20:04:35.349680Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_2",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-3.5-flash",
      "createTime": "2024-05-30T21:14:39.880235Z",
      "updateTime": "2024-05-31T00:21:15.350969Z",
      "expireTime": "2024-05-31T01:21:15.348014Z"
    },
    {
      "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID_N",
      "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-3.5-flash",
      "createTime": "2024-05-30T21:14:39.880235Z",
      "updateTime": "2024-05-31T00:21:15.350969Z",
      "expireTime": "2024-05-31T01:21:15.348014Z"
    }
  ]
}

Exemple de commande curl

LOCATION="us-central1"
PROJECT_ID="PROJECT_ID"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/cachedContents

Obtenir des informations sur un cache de contexte

Pour obtenir des informations sur un cache de contexte, vous avez besoin de son ID de cache, de l'ID de projetGoogle Cloud auquel il est associé et de la région où la requête de création du cache de contexte a été traitée. L'ID d'un cache de contexte est renvoyé lorsque vous créez le cache de contexte. Vous pouvez également obtenir l'ID de chaque cache de contexte associé à un projet à l'aide de la commande permettant de lister les caches de contexte.

L'exemple suivant montre comment obtenir des informations sur un cache de contexte.

Go

Avant d'essayer cet exemple, suivez les instructions de configuration Go décrites dans le guide de démarrage rapide de l'Agent Platform à l'aide des bibliothèques clientes.

Pour vous authentifier auprès d'Agent Platform, configurez les identifiants par défaut de l'application. Pour en savoir plus, consultez Configurer l'authentification pour un environnement de développement local.

import (
	"context"
	"fmt"
	"io"
	"net/http"
	"time"

	"google.golang.org/genai"
)

// getContentCache shows how to retrieve the metadata of a cached content
// contentName is the ID of the cached content to retrieve
func getContentCache(w io.Writer, contentName string) error {
	ctx := context.Background()

	client, err := genai.NewClient(ctx, &genai.ClientConfig{
		HTTPOptions: genai.HTTPOptions{APIVersion: "v1"},
	})
	if err != nil {
		return fmt.Errorf("failed to create genai client: %w", err)
	}

	cachedContent, err := client.Caches.Get(ctx, contentName, &genai.GetCachedContentConfig{
		HTTPOptions: &genai.HTTPOptions{
			Headers:    http.Header{"X-Custom-Header": []string{"example"}},
			APIVersion: "v1",
		},
	})
	if err != nil {
		return fmt.Errorf("GetCachedContent: %w", err)
	}

	// Print basic info about the cached content
	fmt.Fprintf(w, "Cache name: %s\n", cachedContent.Name)
	fmt.Fprintf(w, "Display name: %s\n", cachedContent.DisplayName)
	fmt.Fprintf(w, "Model: %s\n", cachedContent.Model)
	fmt.Fprintf(w, "Create time: %s\n", cachedContent.CreateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Update time: %s\n", cachedContent.UpdateTime.Format(time.RFC3339))
	fmt.Fprintf(w, "Expire time: %s (in %s)\n", cachedContent.ExpireTime.Format(time.RFC3339), time.Until(cachedContent.ExpireTime).Round(time.Second))

	if cachedContent.UsageMetadata != nil {
		fmt.Fprintf(w, "Usage metadata: %+v\n", cachedContent.UsageMetadata)
	}

	// Example response:
	// Cache name: projects/111111111111/locations/us-central1/cachedContents/1234567890123456789
	// Display name: product_recommendations_prompt
	// Model: models/gemini-2.5-flash
	// Create time: 2025-04-08T02:15:23Z
	// Update time: 2025-04-08T03:05:11Z
	// Expire time: 2025-04-20T03:05:11Z (in 167h59m59s)
	// Usage metadata: &{AudioDurationSeconds:0 ImageCount:167 TextCount:153 TotalTokenCount:43124 VideoDurationSeconds:0}
	return nil
}

REST

L'exemple suivant montre comment utiliser REST pour lister les caches de contexte associés à un projet Google Cloud en envoyant une demande GET au point de terminaison du modèle de l'éditeur.

Avant d'utiliser les données de requête, effectuez les remplacements suivants :

• PROJECT_ID: .
• LOCATION : région dans laquelle la requête de création de cache de contexte a été traitée.
• CACHE_ID : ID du cache de contexte. L'ID du cache de contexte est renvoyé lorsque vous créez le cache de contexte. Vous pouvez également trouver les ID de cache de contexte en listant les caches de contexte d'un projet Google Cloud . Pour en savoir plus, consultez Créer un cache de contexte et Obtenir la liste des caches de contexte.

Méthode HTTP et URL :

GET https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID

Pour envoyer votre requête, choisissez l'une des options suivantes :

curl

Remarque : Pour la commande suivante, nous partons du principe que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login, ou en utilisant Cloud Shell, qui vous connecte automatiquement à la CLI gcloud. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

curl -X GET \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID"

PowerShell

Remarque : La commande suivante suppose que vous vous êtes connecté à la CLI gcloud avec votre compte utilisateur en exécutant la commande gcloud init ou gcloud auth login. Vous pouvez exécuter la commande gcloud auth list pour vérifier quel est le compte actuellement actif.

Exécutez la commande suivante :

$cred = gcloud auth print-access-token
$headers = @{ "Authorization" = "Bearer $cred" }

Invoke-WebRequest `
    -Method GET `
    -Headers $headers `
    -Uri "https://LOCATION-aiplatform.googleapis.com/v1/projects/PROJECT_ID/locations/LOCATION/cachedContents/CACHE_ID" | Select-Object -Expand Content

Vous devriez recevoir une réponse JSON de ce type :

Réponse

{
  "name": "projects/PROJECT_NUMBER/locations/us-central1/cachedContents/CACHE_ID",
  "model": "projects/PROJECT_ID/locations/us-central1/publishers/google/models/gemini-3.5-flash",
  "createTime": "2024-05-31T19:04:35.380412Z",
  "updateTime": "2024-05-31T19:04:35.380412Z",
  "expireTime": "2024-05-31T20:04:35.349680Z"
}

Exemple de commande curl

LOCATION="us-central1"
PROJECT_ID="PROJECT_ID"
CACHE_ID="CACHE_ID"

curl \
-X GET \
-H "Authorization: Bearer $(gcloud auth print-access-token)" \
https://${LOCATION}-aiplatform.googleapis.com/v1/projects/${PROJECT_ID}/locations/${LOCATION}/${CACHE_ID}

Étape suivante

• Découvrez comment utiliser un cache de contexte.
• Découvrez comment mettre à jour le délai d'expiration d'un cache de contexte.
• Découvrez comment supprimer un cache de contexte.