داده‌واحد مصورسازی داده‌های عامل‌گرا

نشان دیداری‌سازی داده‌های عامل به برنامه عامل شما اجازه می‌دهد عناصر کیت میانای کاربر «جاها» را برای مکان‌های موجود در پاسخ ابزارهای عامل Maps Experience (قبلاً Maps Grounding Lite) بدون هزینه اضافی نمایش دهد. هر فراخوانی موفق به ابزار search_places یا search_along_route یک توکن برمی‌گرداند که مکان‌ها را در پاسخ شناسایی می‌کند، هم برای SKUهای Essentials و هم Pro. وقتی که برنامه کارخواه شما این نمانه را به Maps JavaScript API، «کیت توسعه نرم‌افزار مکان‌ها، ویژه Android»، یا «کیت توسعه نرم‌افزار مکان‌ها، ویژه iOS» اضافه می‌کند، درخواست‌های «کیت میانای کاربر مکان‌ها» برای آن مکان‌ها تا ۱۰ دقیقه پس‌از صدور نمانه صورت‌حساب نمی‌شود.

روش کار

این کد پاسخ مستدل را به جزئیات مکانی که با آن نمایش می‌دهید متصل می‌کند:

  1. عامل شما ابزار search_places یا search_along_route را در سرور MCP ابزارهای عامل Maps Experience فراخوانی می‌کند. پاسخ ابزار شامل مکان‌هایی است که از خلاصه پشتیبانی می‌کنند و یک توکن در فیلد contentToken.
  2. برنامه شما توکن را از پاسخ ابزار می‌خواند و آن را به‌همراه شناسه‌های مکان‌هایی که می‌خواهید نمایش دهید به برنامه کارخواه شما ارسال می‌کند.
  3. برنامه کارخواه شما این کد را به Maps JavaScript API اضافه می‌کند یا آن را در هر درخواست مؤلفه تلفن همراه ارسال می‌کند و عناصر «کیت میانای کاربر جاها» را برای آن مکان‌ها ایجاد می‌کند.
  4. Google Maps Platform با هر درخواست «کیت میانای کاربر جاها»، کد را اعتبارسنجی می‌کند. اگر توکن معتبر باشد، درخواست صورت‌حساب نمی‌شود.

عناصر پشتیبانی‌شده کیت میانای کاربر «جاها»

Maps JavaScript API

این کد به عناصر «کیت میانای کاربر جاها» در میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps اعمال می‌شود:

عنصر واحد نگهداری موجودی
PlaceDetailsElement پرس‌وجوی کیت میانای کاربر «جاها»
PlaceDetailsCompactElement پرس‌وجوی کیت میانای کاربر «جاها»
AdvancedPlaceDetailsElement Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactElement Places UI Kit Pro (Advanced)
AdvancedPlaceListElement Places UI Kit Pro (Advanced)

کیت توسعه نرم‌افزار مکان‌ها، ویژه Android

تابع ترکیب‌پذیر/قطعه واحد نگهداری موجودی
PlaceDetailsFragment پرس‌وجوی کیت میانای کاربر «جاها»
PlaceDetailsCompactFragment پرس‌وجوی کیت میانای کاربر «جاها»
AdvancedPlaceDetailsFragment Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactFragment Places UI Kit Pro (Advanced)
AdvancedPlaceListFragment Places UI Kit Pro (Advanced)
AdvancedPlaceDetails Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompact Places UI Kit Pro (Advanced)
PlaceMarker Places UI Kit Pro (Advanced)

کیت توسعه نرم‌افزار مکان‌ها، ویژه iOS

ساختار واحد نگهداری موجودی
PlaceDetailsView پرس‌وجوی کیت میانای کاربر «جاها»
PlaceDetailsCompactView پرس‌وجوی کیت میانای کاربر «جاها»
AdvancedPlaceDetailsView Places UI Kit Pro (Advanced)
AdvancedPlaceDetailsCompactView Places UI Kit Pro (Advanced)
AdvancedPlaceListView Places UI Kit Pro (Advanced)
PlaceMarker Places UI Kit Pro (Advanced)

این کد به درخواست‌های دیگر، مانند درخواست‌های عناصر «جستجوی جا»، «جستجوی پیشرفته جا»، و «تکمیل خودکار جا»ی پایه، درخواست‌های Places API، و بارگیری‌های نقشه اعمال نمی‌شود. این درخواست‌ها با نرخ‌های استاندارد صورت‌حساب می‌شوند.

فقط پاسخ‌های ابزارهای عامل Maps Experience حاوی این کد هستند. اگر جاهای برگرفته از پاسخ «پایه‌مندسازی با Google Maps» را با «کیت میانای کاربر جاها» نمایش دهید، هزینه آن درخواست‌ها با نرخ استاندارد محاسبه می‌شود.

قبل‌از شروع

قبل‌از استفاده از کد داده‌نمایی عاملی، موارد زیر را راه‌اندازی کنید:

  • پروژه Google Cloud با Maps Experience agent tools API (mapstools.googleapis.com) و Places UI Kit API فعال‌شده. برای اطلاعات بیشتر، پیکربندی مدل‌های زبانی بزرگ برای استفاده از سرور MCP و شروع به کار با «کیت میانای کاربر جاها» برای JavaScript، Android، یا iOS را ببینید.
  • اعتبارنامه‌های آن پروژه برای هر دو تماس ابزارهای عامل Maps Experience و میانای برنامه‌سازی کاربردی جاوا اسکریپت در Maps، کیت توسعه نرم‌افزار Places برای Android، یا کیت توسعه نرم‌افزار Places برای iOS. یک توکن فقط برای درخواست‌های «کیت میانای کاربر جاها» از پروژه‌ای که توکن برای آن صادر شده است معتبر است.
  • برنامه کارخواهی که Maps JavaScript API را با تنظیم v=beta از کانال بتا بار می‌کند. برای تلفن همراه، از «کیت توسعه نرم‌افزار مکان‌ها» برای Android نسخه ۶.۱.۰ یا جدیدتر یا «کیت توسعه نرم‌افزار مکان‌ها» Swift‏ (GooglePlacesSwift) نسخه ۱۱.۴.۰ استفاده کنید.

نمایش مکان‌ها از پاسخ مستند

بخش‌های زیر نشان می‌دهند که چگونه کد را از پاسخ ابزار دریافت کنید و از آن در برنامه کارخواه خود استفاده کنید. اگر از ابزار کار میانای کاربر عامل‌گرای Maps (آزمایشی) استفاده می‌کنید، عامل و کارخواه وب آن این مراحل را برای شما انجام می‌دهند.

دریافت کردن توکن از پاسخ ابزار

ابزارهای search_places و search_along_route کد را در فیلد contentToken برمی‌گردانند. در نتیجه درخواست MCP tools/call، این فیلد در structuredContent است. در پاسخ از روش REST searchText یا searchAlongRoute، این فیلد در سطح بالا قرار دارد. پاسخ search_places مشابه پاسخ زیر است (پاسخ search_along_route هر مکان را در results[].place برمی‌گرداند):

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

این خروجی شامل مقادیر زیر است:

  • ‫PLACE_ID: شناسه مکان مکانی در پاسخ.
  • CONTENT_TOKEN: کد دیداری‌سازی داده‌های عاملی برای مکان‌های موجود در پاسخ. با این کد به‌عنوان رشته‌ای مبهم رفتار کنید و آن را تغییر ندهید.

اگر پاسخ شامل هیچ مکانی نباشد، پاسخ شامل هیچ نشانه‌ای نیست.

در کد برنامه‌تان، کد را از پاسخ ابزار بخوانید (برای مثال، در یک فراخوانی ابزار در چارچوب عاملتان) و آن را با شناسه‌های مکان به برنامه کارخواهتان ارسال کنید. به LLM برای تکرار کردن کد در خروجی‌اش تکیه نکنید، زیرا مدل ممکن است کد را تغییر دهد.

هر کد فقط مکان‌های موجود در پاسخ خودش را پوشش می‌دهد. اگر عاملتان بیش‌از یک‌بار با search_places یا search_along_route تماس گرفت، هرکدام از این کدها را به برنامه مشتری‌تان ارسال کنید.

برای مثال، اگر از کیت توسعه عامل (ADK) برای Python استفاده می‌کنید، می‌توانید هر توکن را در یک فراخوانی برگشتی پس‌از ابزار ذخیره کنید:

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

هنگام ایجاد کردن نماینده، این تابع را به‌عنوان آرگومان after_tool_callback ارسال کنید و سپس توکن‌های ذخیره‌شده را با پاسخ نماینده به برنامه کارخواه ارسال کنید. برای تعاریف کامل عامل، نمونه‌های ADK را در پیکربندی کردن مدل‌های زبانی بزرگ برای استفاده از سرور MCP ببینید.

افزودن کد و نمایش مکان‌ها

Maps JavaScript API

در برنامه کارخواه، قبل‌از ایجاد عناصر «کیت میانای کاربر جاها» برای مکان‌ها، یک تکرارپذیر (مانند آرایه) از رشته‌های کد غیرخالی را به Settings.getInstance().addContentTokens() ارسال کنید. اگر یک رشته را مستقیماً ارسال کنید یا اگر تکرارپذیر شامل رشته خالی باشد، این روش خطا ایجاد می‌کند. مثال زیر یک توکن اضافه می‌کند و سپس عنصر «جزئیات فشرده مکان» را برای هر مکان نمایش می‌دهد:

// 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);
  }
}

توکن‌ها ۱۰ دقیقه پس‌از صدور منقضی می‌شوند. Maps JavaScript API نشان‌هایی را که به حافظه صفحه فعلی اضافه می‌کنید نگه می‌دارد و پس‌از منقضی شدن، آن‌ها را به‌طور خودکار برمی‌دارد، بنابراین نیازی نیست نشان‌های منقضی‌شده را خودتان بردارید. اگر از بیش‌از یک پاسخ، کد اضافه کنید، API همه کدهای ذخیره‌شده را با هر درخواست از عنصر پشتیبانی‌شده ارسال می‌کند.

برای نمایش چندین مکان در یک عنصر، ویژگی places عنصر «فهرست مکان پیشرفته» را روی شناسه‌های مکان از یک یا چند پاسخ که توکن‌های آن‌ها را اضافه کرده‌اید تنظیم کنید.

کیت توسعه نرم‌افزار مکان‌ها، ویژه Android

contentTokens: Set<String> را مستقیماً در هر پُرسمان عنصر ارسال کنید.

توکن‌ها ۱۰ دقیقه پس‌از صدور منقضی می‌شوند. کیت توسعه نرم‌افزار توکن‌ها را در درخواست‌ها ذخیره نمی‌کند یا انقضا را ردیابی نمی‌کند.

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

قطعات (PlaceDetailsFragment، PlaceDetailsCompactFragment، AdvancedPlaceDetailsFragment، AdvancedPlaceDetailsCompactFragment):

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

قطعه فهرست مکان (AdvancedPlaceListFragment):

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

کیت توسعه نرم‌افزار مکان‌ها، ویژه iOS

کیت توسعه نرم‌افزار موارد شمارشی PlaceIdentifier اختصاصی (.placeIDWithTokens یا .resourceNameWithTokens) ارائه می‌دهد که به مقداردهی‌های اولیه PlaceDetailsQuery(identifier:) و PlaceMarker(identifier:...) موجود ارسال می‌شوند.

توکن‌ها ۱۰ دقیقه پس‌از صدور منقضی می‌شوند. کیت توسعه نرم‌افزار توکن‌ها را در درخواست‌ها ذخیره نمی‌کند یا انقضا را ردیابی نمی‌کند.

// 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
)

اعتبارسنجی کد

درخواست «کیت میانای کاربر جاها» درصورت برآورده شدن همه شرایط زیر صورت‌حساب نمی‌شود:

  • پروژه یکسان: این توکن‌ها برای پروژه Google Cloud صادر شده‌اند که مالک کلید میانای برنامه‌سازی کاربردی است که برای بار کردن Maps JavaScript API،‏ Places SDK for Android، یا Places SDK for iOS استفاده می‌کنید.
  • مکان‌های مستند: هر مکانی که عنصر درخواست می‌کند حداقل با یک کد موجود در درخواست پوشش داده می‌شود. اگر کد هر پاسخ را اضافه کنید، یک عنصر می‌تواند شامل مکان‌هایی از چندین پاسخ باشد.
  • کدهای منقضی‌نشده: برای هر مکان، درخواست ظرف ۱۰ دقیقه از زمان صدور کدی که آن مکان را پوشش می‌دهد انجام می‌شود.
  • عنصر پشتیبانی‌شده: درخواست از عنصر یا مؤلفه پشتیبانی‌شده کیت میانای کاربر «جاها» ارسال شده است.

عناصری که به‌جای مکان با موقعیت پیکربندی می‌کنید، مثل PlaceDetailsLocationRequestElement، پوشش داده نمی‌شوند. اگر عنصر «فهرست مکان‌های پیشرفته» شامل مکانی باشد که تحت پوشش نیست، کل درخواست صورت‌حساب می‌شود.

اگر هریک از شرایط برآورده نشود، عنصر همچنان بار می‌شود و درخواست با نرخ استاندارد برای SKU آن صورت‌حساب می‌شود. «میانای برنامه‌سازی کاربردی جاوا اسکریپت Maps»، «کیت توسعه نرم‌افزار مکان‌ها» برای Android، و «کیت توسعه نرم‌افزار مکان‌ها» برای iOS درصورت نامعتبر بودن کد خطایی برنمی‌گردانند.

محدودیت‌ها (فقط کیت توسعه نرم‌افزار مکان‌ها برای Android و iOS)

  • حداکثر ۱۰۰ کد یکتا برای هر درخواست وجود دارد. کدهای اضافی با گزارش هشدار کوتاه می‌شوند.
  • حداکثر ۲۰۴۸ بایت UTF-8 برای هر کد وجود دارد. نشان‌های بیش‌ازحد بزرگ با گزارش هشدار حذف می‌شوند و موارد خالی یا تکراری نادیده گرفته می‌شوند.
  • پرس‌وجوهای مختصات (PlaceReference.Coordinates و PlaceIdentifier.coordinate) توکن نمی‌پذیرند.
  • در iOS AdvancedPlaceListView، اگر هر پُرسمانی در فهرست فاقد شناسه مکان یا نام منبع غیرخالی باشد، هیچ کدی برای فهرست ارسال نمی‌شود.

صورت‌حساب

برای هر درخواست ابزارهای عامل Maps Experience، هزینه آن را با نرخ استاندارد پرداخت می‌کنید. درخواست‌های «کیت میانای کاربر جاها» که اعتبارسنجی کد را می‌گذرانند صورت‌حساب نمی‌شوند، اما همچنان در سهمیه «کیت میانای کاربر جاها» شما محاسبه می‌شوند. درخواست‌هایی که اعتبارسنجی کد را با موفقیت پشت سر نمی‌گذارند، یا درخواست‌هایی که کد نامعتبر یا منقضی‌شده دارند، با نرخ استاندارد برای شناسه محصول پرس‌وجوی کیت میانای کاربر «جاها» یا کیت میانای کاربر «جاها» Pro (پیشرفته) صورت‌حساب می‌شوند.

برای قیمت‌ها، جدول قیمت‌گذاری اصلی و جدول قیمت‌گذاری هند را ببینید.

الزامات استفاده

فقط برای استفاده تک‌کاربره و پاسخ فعال: باید از کد تجسم داده‌های عاملی فقط برای نمایش عناصر پشتیبانی‌شده «کیت میانای کاربر جاها» به همان کاربر نهایی و در پاسخ عاملی فوری که کد را تولید کرده است استفاده کنید. نباید نشان‌ها را بین چند کاربر نهایی هم‌رسانی کنید، ادغام کنید، یا مجدداً استفاده کنید، یا از نشان برای نمایش مکان‌های خارج از آن پاسخ (مثلاً در فهرست‌های ذخیره‌شده، نشانک‌ها، یا دایرکتوری‌های ذخیره‌شده در حافظه نهان) استفاده کنید.

استفاده شما از کد تجسم داده‌های عاملی تابع شرایط خدمات Google Maps Platform، ازجمله شرایط خاص سرویس است. الزامات ذکر منبع برای ابزارهای عامل Maps Experience نیز اعمال می‌شود.