MCP Tools Reference: mapstools.googleapis.com

الأداة: resolve_maps_urls

تحوّل هذه الطريقة قائمة بعناوين URL على "خرائط Google" إلى أرقام تعريف أساسية للأماكن على "خرائط Google".

متى يجب استدعاء هذه الأداة (مهم):

  • استخدِم هذه الأداة عندما يقدّم المستخدِم رابطًا أو أكثر من روابط أو عناوين URL للمشاركة في "خرائط Google" (مثل "https://maps.app.goo.gl/..." أو "https://www.google.com/maps/place/..." أو "https://maps.google.com/...") وتحتاج إلى استخراج معرّفات الأماكن الأساسية الأساسية.
  • يمكنك تحديد ما يصل إلى 20 عنوان URL ليتم حلّها في طلب دُفعة واحد.

متطلبات الإدخال (مهمة):

  • urls (مصفوفة من السلاسل - إلزامي): قائمة بعناوين URL التي يجب تحليلها في "خرائط Google". يجب أن يكون كل عنوان URL صالحًا ويؤدي إلى مكان واحد على "خرائط Google".

التعامل مع الأخطاء (مهم):

  • هذه أداة معالجة على دفعات، وقد يعرض الطلب "نتائج مختلطة" (مثل معالجة بعض عناوين URL بنجاح وتعذُّر معالجة البعض الآخر).
  • يُضمَن أن تتطابق قائمة النتائج entities مع فهارس الإدخال urls بنسبة 1:1. وسيؤدي تعذُّر تحليل عنوان URL إلى ظهور رسالة Entity فارغة (لم يتم ضبط أي حقول) في الفهرس المقابل في قائمة entities.
  • يجب التحقّق من حقل خريطة failed_requests في الردّ لتحديد فهرس عنوان URL المحدّد الذي تعذّر تنفيذه. يمثّل مفتاح failed_requests الفهرس المستند إلى الرقم 0 لعنوان URL الذي تعذّر تنفيذه في الطلب. لا تفترض أنّه تعذّر تنفيذ عملية طلب الدفعة بالكامل بسبب تعذّر تنفيذ جزء منها.

يوضّح المثال التالي كيفية استخدام curl لاستدعاء أداة resolve_maps_urls MCP.

طلب Curl 
                  
curl --location 'https://mapstools.googleapis.com/mcp' \
--header 'content-type: application/json' \
--header 'accept: application/json, text/event-stream' \
--data '{
  "method": "tools/call",
  "params": {
    "name": "resolve_maps_urls",
    "arguments": {
      // provide these details according to the tool's MCP specification
    }
  },
  "jsonrpc": "2.0",
  "id": 1
}'

مخطط الإدخال

رسالة الطلب الخاصة بـ ResolveMapsUrls

ResolveMapsUrlsRequest

تمثيل JSON 
{
  "urls": [
    string
  ]
}
الحقول
urls[]

string

الحقل مطلوب. عناوين URL التي سيتم تحليلها في "خرائط Google" يجب أن يكون كل عنوان URL صالحًا على "خرائط Google"، مثل https://maps.app.goo.gl/... أو https://www.google.com/maps/place/... أو https://maps.google.com/.... في الوقت الحالي، لا تتوفّر سوى عناوين URL التي تشير إلى مكان واحد. يمكنك تحديد ما يصل إلى 20 عنوان URL.

مخطط الناتج

رسالة الردّ على ResolveMapsUrls

ResolveMapsUrlsResponse

تمثيل JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
الحقول
entities[]

object (Entity)

هذا الحقل مخصّص للناتج فقط. وهو يتضمّن قائمة بالعناصر التي تم تحديدها من عناوين URL في "خرائط Google". ويتم ضمان الربط بنسبة 1:1 مع فهارس الطلب urls. تشير الرسالة الفارغة في الفهرس i (حيث لم يتم ضبط entity) إلى تعذُّر تحديد عنوان URL هذا. وفي حال تعذُّر تحديد عنوان URL، يُرجى التحقّق من الحقل failed_requests لمعرفة حالة الخطأ.
failedRequests

map (key: integer, value: object (Status))

للقراءة فقط. خريطة تعرض حالات تعذُّر جزئي لعناوين URL في "خرائط Google". المفتاح هو فهرس الطلب الذي تعذّر تنفيذه في الحقل urls. والقيمة هي حالة الخطأ التي توضّح سبب تعذُّر تحديد الموقع الجغرافي.

كائن يحتوي على قائمة بأزواج "key": value، مثل: { "name": "wrench", "mass": "1.3kg", "count": "3" }

الكيان

تمثيل JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
الحقول
حقل الربط entity نوع الكيان الذي تمّت تسويته. يمكن أن يكون التعليق entity إحدى القيم التالية فقط:
place

string

اسم المورد الخاص بالمكان الذي تم تحديد موقعه الجغرافي.

FailedRequestsEntry

تمثيل JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
الحقول
key

integer
value

object (Status)

الحالة

تمثيل JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
الحقول
code

integer

هو رمز الحالة، ويجب أن يكون قيمة محدّدة مسبقًا من google.rpc.Code.
message

string

يشير إلى رسالة خطأ موجّهة للمطوّرين، ويجب أن تكون الرسالة بالإنجليزية. أما رسائل الخطأ الموجّهة للمستخدمين، فيجب ترجمتها وإرسالها في حقل google.rpc.Status.details أو ترجمتها من قِبل العميل.
details[]

object

يشير إلى قائمة بالرسائل التي تتضمّن تفاصيل الخطأ. تتوفّر مجموعة شائعة من أنواع الرسائل التي يمكن لواجهات برمجة التطبيقات استخدامها.

هو كائن يحتوي على حقول من أي نوع، بالإضافة إلى حقل "@type" الذي يتضمّن معرف موارد منتظم (URI) يحدّد نوع الكائن، مثل { "id": 1234, "@type": "types.example.com/standard/id" }.

أي

تمثيل JSON 
{
  "typeUrl": string,
  "value": string
}
الحقول
typeUrl

string

تحدّد هذه السمة نوع رسالة Protobuf المتسلسلة باستخدام مرجع URI يتألف من بادئة تنتهي بشرطة مائلة واسم النوع المؤهَّل بالكامل.

مثال: type.googleapis.com/google.protobuf.StringValue

يجب أن يحتوي هذا السلسلة على حرف / واحد على الأقل، ويجب أن يكون المحتوى بعد آخر / هو الاسم المؤهّل بالكامل للنوع في النموذج الأساسي، بدون نقطة بادئة. لا تكتب مخططًا على مراجع URI هذه حتى لا تحاول البرامج الاتصال بها.

البادئة اختيارية، ومن المتوقّع أن تزيل عمليات تنفيذ Protobuf كل ما يسبق آخر / بما في ذلك، وذلك لتحديد النوع. ‫type.googleapis.com/ هو بادئة تلقائية شائعة تتطلّبها بعض عمليات التنفيذ القديمة. لا تشير هذه البادئة إلى مصدر النوع، ولا يُتوقّع أن تستجيب معرّفات الموارد المنتظمة التي تحتوي عليها لأي طلبات.

يجب أن تكون جميع سلاسل عناوين URL من النوع مراجع URI قانونية مع القيود الإضافية (بالنسبة إلى تنسيق النص) التي يجب أن يتألف محتوى المرجع منها فقط من أحرف أبجدية رقمية وعلامات هروب مشفّرة بالنسبة المئوية وأحرف في المجموعة التالية (لا يشمل ذلك علامات الاقتباس المائلة الخارجية): /-.~_!$&()*+,;=. على الرغم من سماحنا بعمليات التشفير بالنسبة المئوية، يجب ألا تزيل عمليات التنفيذ علامات الهروب لمنع حدوث لبس مع المحلّلات الحالية. على سبيل المثال، يجب رفض type.googleapis.com%2FFoo.

في التصميم الأصلي لـ Any، تمّت مراعاة إمكانية تشغيل خدمة تحليل الأنواع في عناوين URL هذه، ولكن لم تنفّذ Protobuf أي خدمة من هذا النوع، وتعتبر أنّ الاتصال بعناوين URL هذه يمثّل مشكلة وأحد المشاكل الأمنية المحتملة. لذا، لا تحاول الاتصال بعناوين URL الخاصة بالأنواع.
value

string (bytes format)

تحتوي على تسلسل Protobuf للنوع الموصوف بواسطة type_url.

سلسلة مرمّزة باستخدام Base64

التعليقات التوضيحية للأدوات

Destructive Hint: ❌ | Idempotent Hint: ❌ | Read Only Hint: ✅ | Open World Hint: ❌