MCP Tools Reference: mapstools.googleapis.com

Công cụ: resolve_maps_urls

Phân giải danh sách URL Google Maps thành Mã địa điểm chính tắc trên Google Maps.

Thời điểm gọi công cụ này (QUAN TRỌNG):

  • Hãy sử dụng công cụ này khi người dùng cung cấp một hoặc nhiều đường liên kết hoặc URL chia sẻ trên Google Maps (ví dụ: "https://maps.app.goo.gl/...", "https://www.google.com/maps/place/..." hoặc "https://maps.google.com/...") và bạn cần trích xuất Mã địa điểm chính tắc cơ bản.
  • Bạn có thể chỉ định tối đa 20 URL để phân giải trong một yêu cầu hàng loạt.

Yêu cầu về dữ liệu đầu vào (QUAN TRỌNG):

  • urls (mảng chuỗi – BẮT BUỘC): Danh sách URL Google Maps cần phân giải. Mỗi URL phải là một URL Google Maps hợp lệ cho một địa điểm.

Xử lý lỗi (QUAN TRỌNG):

  • Đây là công cụ xử lý hàng loạt. Một yêu cầu có thể trả về "kết quả hỗn hợp" (ví dụ: một số URL phân giải thành công trong khi các URL khác không thành công).
  • Danh sách đầu ra của entities được đảm bảo liên kết 1:1 với các chỉ mục urls đầu vào. Việc phân giải URL không thành công sẽ dẫn đến thông báo Entity trống (không có trường nào được đặt) tại chỉ mục tương ứng trong danh sách entities.
  • Bạn PHẢI kiểm tra trường bản đồ failed_requests trong phản hồi để xác định chỉ mục URL cụ thể nào không thành công. Khoá của failed_requests đại diện cho chỉ mục dựa trên 0 của URL không thành công trong yêu cầu. Đừng cho rằng toàn bộ lệnh gọi hàng loạt không thành công chỉ vì một phần không thành công.

Mẫu sau đây minh hoạ cách sử dụng curl để gọi công cụ resolve_maps_urls MCP.

Yêu cầu 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
}'

Giản đồ đầu vào

Thông báo yêu cầu cho ResolveMapsUrls.

ResolveMapsUrlsRequest

Biểu diễn dưới dạng JSON 
{
  "urls": [
    string
  ]
}
Trường
urls[]

string

Bắt buộc. URL Google Maps cần được phân giải. Mỗi URL phải là một URL Google Maps hợp lệ, ví dụ: https://maps.app.goo.gl/..., https://www.google.com/maps/place/..., hoặc https://maps.google.com/.... Hiện tại, chúng tôi chỉ hỗ trợ các URL trỏ đến một địa điểm. Bạn có thể chỉ định tối đa 20 URL.

Giản đồ đầu ra

Thông báo phản hồi cho ResolveMapsUrls.

ResolveMapsUrlsResponse

Biểu diễn dưới dạng JSON 
{
  "entities": [
    {
      object (Entity)
    }
  ],
  "failedRequests": {
    integer: {
      object (Status)
    },
    ...
  }
}
Trường
entities[]

object (Entity)

Chỉ có đầu ra. Danh sách các thực thể đã phân giải từ URL Google Maps. Đảm bảo liên kết 1:1 với các chỉ mục urls yêu cầu. Một thông báo trống tại chỉ mục i (nơi không có entity nào được đặt) cho biết quá trình phân giải không thành công đối với URL đó. Nếu quá trình phân giải không thành công, vui lòng kiểm tra trường failed_requests để biết trạng thái lỗi.
failedRequests

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

Chỉ có đầu ra. Một bản đồ thông báo các lỗi một phần cho URL Google Maps. Khoá là chỉ mục của yêu cầu không thành công trong trường urls. Giá trị là trạng thái lỗi nêu chi tiết lý do quá trình phân giải không thành công.

Một đối tượng chứa danh sách các cặp "key": value. Ví dụ: { "name": "wrench", "mass": "1.3kg", "count": "3" }.

Thực thể

Biểu diễn dưới dạng JSON 
{

  // Union field entity can be only one of the following:
  "place": string
  // End of list of possible types for union field entity.
}
Trường
Trường nhóm entity. Loại thực thể đã phân giải. entity chỉ có thể là một trong những loại sau:
place

string

Tên tài nguyên của địa điểm đã phân giải.

FailedRequestsEntry

Biểu diễn dưới dạng JSON 
{
  "key": integer,
  "value": {
    object (Status)
  }
}
Trường
key

integer
value

object (Status)

Trạng thái

Biểu diễn dưới dạng JSON 
{
  "code": integer,
  "message": string,
  "details": [
    {
      "@type": string,
      field1: ...,
      ...
    }
  ]
}
Trường
code

integer

Mã trạng thái, phải là giá trị enum của google.rpc.Code.
message

string

Thông báo lỗi dành cho nhà phát triển, phải bằng tiếng Anh. Mọi thông báo lỗi mà người dùng thấy đều phải được bản địa hoá và gửi trong trường google.rpc.Status.details hoặc được ứng dụng khách bản địa hoá.
details[]

object

Danh sách các thông báo chứa thông tin cụ thể về lỗi. Có một nhóm gồm nhiều loại thông báo chung để API sử dụng.

Một đối tượng chứa các trường thuộc một loại tuỳ ý. Một trường bổ sung "@type" chứa một URI xác định loại. Ví dụ: { "id": 1234, "@type": "types.example.com/standard/id" }.

Bất kỳ

Biểu diễn dưới dạng JSON 
{
  "typeUrl": string,
  "value": string
}
Trường
typeUrl

string

Xác định loại thông báo Protobuf được tuần tự hoá bằng một tham chiếu URI bao gồm tiền tố kết thúc bằng dấu gạch chéo và tên loại đủ điều kiện.

Ví dụ: type.googleapis.com/google.protobuf.StringValue

Chuỗi này phải chứa ít nhất một ký tự / và nội dung sau dấu / cuối cùng phải là tên đủ điều kiện của loại ở dạng chính tắc, không có dấu chấm ở đầu. Đừng viết lược đồ trên các tham chiếu URI này để ứng dụng khách không cố gắng liên hệ với chúng.

Tiền tố là tuỳ ý và các cách triển khai Protobuf dự kiến sẽ chỉ loại bỏ mọi thứ cho đến và bao gồm cả dấu / cuối cùng để xác định loại. type.googleapis.com/ là tiền tố mặc định phổ biến mà một số cách triển khai cũ yêu cầu. Tiền tố này không cho biết nguồn gốc của loại và các URI chứa tiền tố này không được mong đợi phản hồi bất kỳ yêu cầu nào.

Tất cả các chuỗi URL loại phải là tham chiếu URI hợp lệ với hạn chế bổ sung (đối với định dạng văn bản) là nội dung của tham chiếu chỉ được chứa các ký tự chữ và số, ký tự thoát được mã hoá phần trăm và các ký tự trong tập hợp sau (không bao gồm dấu gạch ngược bên ngoài): /-.~_!$&()*+,;=. Mặc dù chúng tôi cho phép mã hoá phần trăm, nhưng các cách triển khai không được bỏ thoát các ký tự này để tránh nhầm lẫn với các trình phân tích cú pháp hiện có. Ví dụ: type.googleapis.com%2FFoo sẽ bị từ chối.

Trong thiết kế ban đầu của Any, khả năng khởi chạy dịch vụ phân giải loại tại các URL loại này đã được xem xét nhưng Protobuf chưa bao giờ triển khai một dịch vụ và coi việc liên hệ với các URL này là có vấn đề và có thể gây ra vấn đề về bảo mật. Đừng cố gắng liên hệ với các URL loại.
value

string (bytes format)

Chứa quá trình tuần tự hoá Protobuf của loại được mô tả bởi type_url.

Một chuỗi được mã hoá base64.

Chú thích công cụ

Gợi ý mang tính phá hoại: ❌ | Gợi ý về tính chất luỹ đẳng: ❌ | Gợi ý chỉ đọc: ✅ | Gợi ý về thế giới mở: ❌