Temsilci tabanlı veri görselleştirme jetonu

Temsilci tabanlı veri görselleştirme jetonu, temsilci tabanlı uygulamanızın, Haritalar deneyimi ajan araçları (eski adıyla Maps Grounding Lite) yanıtındaki yerler için Places UI Kit öğelerini ek ücret ödemeden göstermesine olanak tanır. search_places veya search_along_route aracına yapılan her başarılı çağrı, hem Essentials hem de Pro SKU'ları için yanıttaki yerleri tanımlayan bir jeton döndürür. İstemci uygulamanız; Maps JavaScript API, Android için Yerler SDK'sı veya iOS için Yerler SDK'sına jeton eklediğinde, bu yerler için Places UI Kit istekleri, jetonun verilmesinden sonraki 10 dakika boyunca faturalandırılmaz.

İşleyiş şekli

Jeton, dayanaklı bir yanıtı, yanıtla birlikte gösterdiğiniz yer ayrıntılarına bağlar:

  1. Temsilciniz, Haritalar deneyimi temsilci araçları MCP sunucusunda search_places veya search_along_route aracını çağırır. Aracın yanıtında, özeti destekleyen yerler ve contentToken alanında bir jeton bulunur.
  2. Uygulamanız, araç yanıtındaki jetonu okur ve göstermek istediğiniz yerlerin kimlikleriyle birlikte istemci uygulamanıza gönderir.
  3. İstemci uygulamanız, jetonu Maps JavaScript API'ye ekler veya her mobil bileşen isteğinde iletir ve bu yerler için Places UI Kit öğeleri oluşturur.
  4. Google Haritalar Platformu, her Places UI Kit isteğinde jetonu doğrular. Jeton geçerliyse istek faturalandırılmaz.

Desteklenen Places UI Kit öğeleri

Maps JavaScript API

Jeton, Maps JavaScript API'deki aşağıdaki Places UI Kit öğeleri için geçerlidir:

Öğe SKU
PlaceDetailsElement Places UI Kit Query
PlaceDetailsCompactElement Places UI Kit Query
AdvancedPlaceDetailsElement Places UI Kit Pro (Gelişmiş)
AdvancedPlaceDetailsCompactElement Places UI Kit Pro (Gelişmiş)
AdvancedPlaceListElement Places UI Kit Pro (Gelişmiş)

Android için Yerler SDK'sı

Fragment/composable işlev SKU
PlaceDetailsFragment Places UI Kit Query
PlaceDetailsCompactFragment Places UI Kit Query
AdvancedPlaceDetailsFragment Places UI Kit Pro (Gelişmiş)
AdvancedPlaceDetailsCompactFragment Places UI Kit Pro (Gelişmiş)
AdvancedPlaceListFragment Places UI Kit Pro (Gelişmiş)
AdvancedPlaceDetails Places UI Kit Pro (Gelişmiş)
AdvancedPlaceDetailsCompact Places UI Kit Pro (Gelişmiş)
PlaceMarker Places UI Kit Pro (Gelişmiş)

iOS için Yerler SDK'sı

Struct SKU
PlaceDetailsView Places UI Kit Query
PlaceDetailsCompactView Places UI Kit Query
AdvancedPlaceDetailsView Places UI Kit Pro (Gelişmiş)
AdvancedPlaceDetailsCompactView Places UI Kit Pro (Gelişmiş)
AdvancedPlaceListView Places UI Kit Pro (Gelişmiş)
PlaceMarker Places UI Kit Pro (Gelişmiş)

Jeton; Yer Arama, Gelişmiş Yer Arama ve Temel Yer Adı Otomatik Tamamlama öğelerinden gelen istekler, Places API istekleri ve harita yüklemeleri gibi diğer istekler için geçerli değildir. Bu istekler standart ücretlerle faturalandırılır.

Yalnızca Haritalar deneyimi temsilci araçları yanıtları jetonu içerir. Google Haritalar ile Temellendirme yanıtındaki yerleri Places UI Kit ile gösterirseniz bu istekler standart ücretlerle faturalandırılır.

Başlamadan önce

Temsilci veri görselleştirme jetonunu kullanmadan önce aşağıdakileri ayarlayın:

  • Maps Experience Agent Tools API (mapstools.googleapis.com) ve Places UI Kit API'nin etkinleştirildiği bir Google Cloud projesi. Daha fazla bilgi için MCP sunucusunu kullanmak için LLM'leri yapılandırma ve JavaScript, Android veya iOS için Places UI Kit'i kullanmaya başlama başlıklı makaleleri inceleyin.
  • Haritalar deneyimi ajan araçları çağrılarınız ve Maps JavaScript API, Android için Yerler SDK'sı veya iOS için Yerler SDK'sı için bu projeden alınan kimlik bilgileri. Jeton, yalnızca jetonun verildiği projeden gelen Places UI Kit istekleri için geçerlidir.
  • v=beta ayarını yaparak Maps JavaScript API'yi beta kanalından yükleyen bir istemci uygulaması. Mobil cihazlar için Android için Yerler SDK'sı 6.1.0 veya sonraki sürümlerini ya da Places Swift SDK (GooglePlacesSwift) 11.4.0 sürümünü kullanın.

Temellendirilmiş yanıttaki yerleri gösterme

Aşağıdaki bölümlerde, aracın yanıtından jetonun nasıl alınacağı ve istemci uygulamanızda nasıl kullanılacağı gösterilmektedir. Haritalar ajan tabanlı kullanıcı arayüzü araç seti'ni (deneysel) kullanıyorsanız aracısı ve web istemcisi bu adımları sizin için gerçekleştirir.

Araç yanıtından jetonu alma

search_places ve search_along_route araçları, jetonu contentToken alanında döndürür. Bir MCP tools/call isteğinin sonucunda bu alan structuredContent biçimindedir. searchText veya searchAlongRoute REST yönteminden gelen yanıtta üst düzey bir alandır. search_places yanıtı, aşağıdakine benzer (search_along_route yanıtı, her yeri results[].place içinde döndürür):

{
  "places": [
    {
      "place": "places/PLACE_ID",
      "id": "PLACE_ID"
    }
  ],
  "contentToken": "CONTENT_TOKEN"
}

Bu çıkış aşağıdaki değerleri içerir:

  • PLACE_ID: Yanıttaki bir yerin yer kimliği.
  • CONTENT_TOKEN: Yanıttaki yerler için temsilci veri görselleştirme jetonu. Jetonu opak bir dize olarak değerlendirin ve değiştirmeyin.

Yanıtta herhangi bir yer yoksa yanıt bir jeton içermez.

Uygulama kodunuzda, araç yanıtındaki jetonu okuyun (örneğin, temsilci çerçevenizdeki bir araç geri çağırma işlevinde) ve yer kimlikleriyle birlikte istemci uygulamanıza gönderin. Model, jetonu değiştirebileceğinden LLM'nin çıktısında jetonu tekrarlayacağına güvenmeyin.

Bir jeton yalnızca kendi yanıtındaki yerleri kapsar. Temsilciniz search_places veya search_along_route yöntemini birden fazla kez çağırırsa her jetonu istemci uygulamanıza gönderin.

Örneğin, Python için Agent Development Kit (ADK) kullanıyorsanız her jetonu bir araç sonrası geri çağırma işlevine kaydedebilirsiniz:

from typing import Any, Optional

from google.adk.tools.base_tool import BaseTool
from google.adk.tools.tool_context import ToolContext


def save_content_token(
    tool: BaseTool,
    args: dict[str, Any],
    tool_context: ToolContext,
    tool_response: dict[str, Any],
) -> Optional[dict[str, Any]]:
    """Saves the agentic data visualization token from a Maps tool response."""
    structured_content = tool_response.get("structuredContent") or {}
    token = structured_content.get("contentToken")
    if token:
        tokens = tool_context.state.get("content_tokens", [])
        tool_context.state["content_tokens"] = tokens + [token]
    # Return None to pass the original tool response to the model.
    return None

Temsilcinizi oluştururken bu işlevi after_tool_callback bağımsız değişkeni olarak iletin ve ardından kaydedilen jetonları temsilcinin yanıtıyla birlikte istemci uygulamanıza gönderin. Temsilci tanımlarının tamamı için LLM'leri MCP sunucusunu kullanacak şekilde yapılandırma bölümündeki ADK örneklerine bakın.

Jetonu ekleme ve yerleri görüntüleme

Maps JavaScript API

İstemci uygulamanızda, yerler için Places UI Kit öğeleri oluşturmadan önce Settings.getInstance().addContentTokens() öğesine boş olmayan jeton dizelerinden oluşan bir yinelenebilir (ör. dizi) iletin. Doğrudan tek bir dize iletirseniz veya yinelenebilir öğe boş bir dize içeriyorsa yöntem bir hata verir. Aşağıdaki örnekte bir jeton eklenir ve ardından her yer için bir Yer Ayrıntıları Kompakt öğesi gösterilir:

// The token and place IDs come from the search_places or search_along_route response.
async function displayGroundedPlaces(contentToken, placeIds) {
  const {Settings} = await google.maps.importLibrary('core');
  const {
    PlaceDetailsCompactElement,
    PlaceDetailsPlaceRequestElement,
    PlaceStandardContentElement,
  } = await google.maps.importLibrary('places');

  // Add the token before you create Places UI Kit elements.
  Settings.getInstance().addContentTokens([contentToken]);

  const container = document.getElementById('agent-response');
  for (const placeId of placeIds) {
    const placeDetails = new PlaceDetailsCompactElement();
    placeDetails.append(
      new PlaceDetailsPlaceRequestElement({place: placeId}),
      new PlaceStandardContentElement(),
    );
    container.append(placeDetails);
  }
}

Jetonların süresi, oluşturulduktan 10 dakika sonra sona erer. Maps JavaScript API, eklediğiniz jetonları geçerli sayfa için bellekte tutar ve süresi dolduktan sonra otomatik olarak kaldırır. Bu nedenle, süresi dolmuş jetonları kendiniz kaldırmanız gerekmez. Birden fazla yanıttan jeton eklerseniz API, depolanan tüm jetonları desteklenen bir öğeden gelen her istekle birlikte gönderir.

Tek bir öğede birden fazla yer göstermek için Gelişmiş Yer Listesi öğesinin places özelliğini, jetonlarını eklediğiniz bir veya daha fazla yanıttaki yer kimliklerine ayarlayın.

Android için Yerler SDK'sı

contentTokens: Set<String> parametresini doğrudan her bileşen sorgusuna iletin.

Jetonların süresi, oluşturulduktan 10 dakika sonra sona erer. SDK, istekler arasında jetonları depolamaz veya geçerlilik süresini izlemez.

Jetpack Compose (AdvancedPlaceDetails, AdvancedPlaceDetailsCompact, PlaceMarker):

val placeRef = PlaceReference.PlaceId(
    placeId = placeId,
    contentTokens = setOf(contentToken),
)
// Or with a resource name:
// PlaceReference.ResourceName(resourceName = resourceName, contentTokens = setOf(contentToken))

Parçalar (PlaceDetailsFragment, PlaceDetailsCompactFragment, AdvancedPlaceDetailsFragment, AdvancedPlaceDetailsCompactFragment):

fragment.loadWithPlaceId(placeId, setOf(contentToken))
// Or: fragment.loadWithResourceName(resourceName, setOf(contentToken))

Yer Listesi Parçası (AdvancedPlaceListFragment):

advancedPlaceListFragment.configureFromPlaceIds(placeIds, setOf(contentToken))
// Or: advancedPlaceListFragment.configureFromResourceNames(resourceNames, setOf(contentToken))

iOS için Yerler SDK'sı

SDK, mevcut PlaceDetailsQuery(identifier:) ve PlaceMarker(identifier:...) başlatıcılara iletilen özel PlaceIdentifier enum durumları (.placeIDWithTokens veya .resourceNameWithTokens) sağlar.

Jetonların süresi, oluşturulduktan 10 dakika sonra sona erer. SDK, istekler arasında jetonları depolamaz veya geçerlilik süresini izlemez.

// Place Details and Advanced Place Details (full and compact):
@State var query = PlaceDetailsQuery(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
)
// Or: .resourceNameWithTokens(resourceName, contentTokens: [contentToken])


// Advanced Place List:
@State var queries = [
  PlaceDetailsQuery(
    identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken])
  )
]
// Place Marker:
PlaceMarker(
  identifier: .placeIDWithTokens(placeId, contentTokens: [contentToken]),
  markerIcon: .type,
  markerText: .rating
)

Jeton doğrulama

Aşağıdaki koşulların tümü karşılandığında Places UI Kit isteği faturalandırılmaz:

  • Aynı proje: Jetonlar; Maps JavaScript API, Android için Yerler SDK'sı veya iOS için Yerler SDK'sı'nı yüklemek üzere kullandığınız API anahtarının sahibi olan Google Cloud projesine verilmiştir.
  • Temellendirilmiş yerler: Öğenin istediği her yer, istekte yer alan en az bir jeton tarafından kapsanır. Her yanıttan jeton eklerseniz bir öğe birden fazla yanıttaki yerleri içerebilir.
  • Süresi dolmamış jetonlar: Her yer için istek, yeri kapsayan bir jetonun verildiği andan itibaren 10 dakika içinde yapılır.
  • Desteklenen öğe: İstek, desteklenen bir Places UI Kit öğesinden veya bileşeninden gelir.

PlaceDetailsLocationRequestElement gibi bir yer yerine konumla yapılandırdığınız öğeler kapsama dahil değildir. Gelişmiş Yer Listesi öğesi, kapsanmayan bir yer içeriyorsa isteğin tamamı faturalandırılır.

Herhangi bir koşul karşılanmazsa öğe yine de yüklenir ve istek, SKU'su için standart ücret üzerinden faturalandırılır. Maps JavaScript API, Android için Yerler SDK'sı ve iOS için Yerler SDK'sı, jeton geçerli olmadığında hata döndürmez.

Sınırlar (yalnızca Android ve iOS için Yerler SDK'sı)

  • İstek başına en fazla 100 benzersiz jeton kullanılabilir. Fazla jetonlar, uyarı günlüğüyle kesilir.
  • Jeton başına maksimum 2.048 UTF-8 baytı sınırı vardır. Çok büyük jetonlar bir uyarı günlüğüyle silinir, boşluklar veya kopyalar yoksayılır.
  • Koordinat sorguları (PlaceReference.Coordinates ve PlaceIdentifier.coordinate) jeton kabul etmez.
  • iOS AdvancedPlaceListView sürümünde, listedeki herhangi bir sorguda boş olmayan bir yer kimliği veya kaynak adı yoksa liste için jeton gönderilmez.

Faturalandırma

Her Haritalar deneyimi ajan araçları isteği için standart ücreti ödersiniz. Jeton doğrulamasını geçen Places UI Kit istekleri faturalandırılmaz ancak Places UI Kit kotanıza dahil edilir. Jeton doğrulamasını geçemeyen Places UI Kit istekleri veya geçersiz ya da süresi dolmuş jetonlar içeren istekler, Places UI Kit Sorgusu veya Places UI Kit Pro (Gelişmiş) SKU'su için standart ücret üzerinden faturalandırılır.

Fiyatlar için Ana fiyatlandırma tablosu ve Hindistan fiyatlandırma tablosu'na bakın.

Kullanım şartları

Yalnızca tek kullanıcı ve etkin yanıt kullanımı: Temsilci tabanlı veri görselleştirme jetonunu yalnızca desteklenen Places UI Kit öğelerini aynı son kullanıcıya ve jetonu oluşturan anlık temsilci tabanlı yanıt içinde göstermek için kullanmanız gerekir. Jetonları birden fazla son kullanıcı arasında paylaşmamalı, birleştirmemeli veya yeniden kullanmamalı ya da bu yanıtın dışındaki yerleri (ör. kayıtlı listeler, yer işaretleri veya önbelleğe alınmış dizinler) göstermek için jeton kullanmamalısınız.

Temsilci veri görselleştirme jetonunu kullanımınız, hizmete özel şartlar da dahil olmak üzere Google Haritalar Platformu Hizmet Şartları'na tabidir. Haritalar deneyimi temsilci araçları için ilişkilendirme şartları da geçerlidir.