Sử dụng mã thông báo phiên với API Thẻ thông tin bản đồ

Nhà phát triển ở Khu vực kinh tế Châu Âu (EEA)

Mã phiên là một phần dữ liệu (một UUID) được dùng trong các lệnh gọi REST để xác định một phiên—một chuỗi các trao đổi thông báo có liên quan. Bạn phải thêm mã phiên vào tất cả các yêu cầu về Ô bản đồ 2D và hình ảnh trong Chế độ xem đường phố. Bạn thêm mã này làm giá trị của tham số session được thêm vào tất cả các URL yêu cầu.

Trong Map Tiles API, mã phiên đại diện cho một tập hợp các tuỳ chọn hiển thị đã xác định. Điều này có nghĩa là bạn không phải truyền một tập hợp các tuỳ chọn hiển thị với mỗi yêu cầu về ô. Bạn có thể sử dụng cùng một mã phiên trên nhiều ứng dụng. Mã phiên hiện có hiệu lực trong 2 tuần kể từ thời điểm phát hành, nhưng điều này có thể thay đổi. Bạn luôn có thể kiểm tra thời gian hết hạn của mã phiên bằng cách xem trường expiry trong thông báo phản hồi.

Yêu cầu về mã phiên

Để yêu cầu mã phiên, hãy gửi yêu cầu HTTPS POST đến điểm cuối createSession, như trong ví dụ sau. Bạn phải gửi yêu cầu có tiêu đề Content-Type: application/json.

curl -X POST -d '{
  "mapType": "streetview",
  "language": "en-US",
  "region": "US"
}' \
-H 'Content-Type: application/json' \
"https://tile.googleapis.com/v1/createSession?key=YOUR_API_KEY"

Các trường bắt buộc

mapType

Loại bản đồ cơ sở. Giá trị này có thể là một trong những giá trị sau:

roadmap
Các ô bản đồ được vẽ tiêu chuẩn của Google Maps.
satellite
Hình ảnh vệ tinh.
terrain
Hình ảnh địa hình. Khi chọn terrain làm loại bản đồ, bạn cũng phải thêm loại lớp layerRoadmap (được mô tả trong phần Trường không bắt buộc section).
streetview
Ảnh toàn cảnh trong Chế độ xem đường phố. Để biết thêm thông tin, hãy xem bài viết Ô bản đồ Chế độ xem đường phố.
language

Thẻ ngôn ngữ IETF chỉ định ngôn ngữ dùng để hiển thị thông tin trên các ô. Ví dụ: en-US chỉ định ngôn ngữ tiếng Anh như được nói ở Hoa Kỳ.

region

Mã nhận dạng khu vực của Kho lưu trữ dữ liệu vị trí chung (hai chữ cái viết hoa) đại diện cho vị trí thực tế của người dùng. Ví dụ: US.

Trường tuỳ chọn

imageFormat
Chỉ định định dạng tệp cần trả về. Các giá trị hợp lệ là jpeg hoặc png. Tệp JPEG không hỗ trợ độ trong suốt, do đó, bạn không nên dùng tệp này cho các ô lớp phủ. Nếu bạn không chỉ định imageFormat, thì hệ thống sẽ tự động chọn định dạng tốt nhất cho ô.
scale

Tăng tỷ lệ kích thước của các phần tử bản đồ (chẳng hạn như nhãn đường) trong khi vẫn giữ nguyên kích thước ô và khu vực phủ sóng của ô mặc định. Việc tăng tỷ lệ cũng làm giảm số lượng nhãn trên bản đồ, giúp giảm tình trạng lộn xộn. Các giá trị sau đây là giá trị scale hợp lệ:

  • scaleFactor1x: Giá trị mặc định.
  • scaleFactor2x: Tăng gấp đôi kích thước nhãn và xoá nhãn tính năng nhỏ.
  • scaleFactor4x: Tăng gấp 4 lần kích thước nhãn và xoá nhãn tính năng nhỏ.

Các ví dụ sau đây minh hoạ hiệu ứng của việc điều chỉnh tỷ lệ các phần tử bản đồ.

Hệ số tỷ lệ 1x Hệ số tỷ lệ 2x
Bản đồ cho thấy hệ số tỷ lệ 1x Bản đồ cho thấy hệ số tỷ lệ 2x
highDpi
Chỉ định có trả về ô có độ phân giải cao hay không. Nếu hệ số tỷ lệ tăng lên, highDpi sẽ được dùng để tăng kích thước của ô. Thông thường, việc tăng hệ số tỷ lệ sẽ phóng to ô kết quả thành hình ảnh có cùng kích thước, làm giảm chất lượng. Với highDpi, kích thước kết quả cũng tăng lên, giúp duy trì chất lượng. DPI là viết tắt của Dots per Inch (Số điểm trên mỗi inch) và High DPI (Độ phân giải cao) có nghĩa là ô hiển thị bằng cách sử dụng nhiều số điểm trên mỗi inch hơn bình thường. Nếu là true, thì số lượng pixel trong mỗi chiều x và y sẽ được nhân với hệ số tỷ lệ (tức là 2x hoặc 4x). Khu vực đưa tin của ô vẫn không thay đổi. Tham số này chỉ hoạt động với các giá trị scale là 2x hoặc 4x. Tham số này không ảnh hưởng đến các ô có tỷ lệ 1x.
Hệ số tỷ lệ 1x Hệ số tỷ lệ 2x Độ phân giải cao
Bản đồ hiển thị ở độ phân giải thông thường Bản đồ hiển thị ở độ phân giải DPI cao gấp 2 lần
layerTypes

Một mảng các giá trị chỉ định các loại lớp được thêm vào bản đồ. Các giá trị hợp lệ là:

layerRoadmap
Bắt buộc nếu bạn chỉ định terrain làm loại bản đồ. Cũng có thể được phủ lên loại bản đồ satellite (không bắt buộc). Không ảnh hưởng đến các ô bản đồ đường đi.
layerStreetview
Hiển thị các đường phố và địa điểm có Chế độ xem đường phố bằng đường viền màu xanh dương trên bản đồ.
layerTraffic
Hiển thị tình trạng giao thông hiện tại.
styles

Một mảng các đối tượng kiểu JSON chỉ định hình thức và mức độ chi tiết của các tính năng trên bản đồ, chẳng hạn như đường, công viên và khu vực xây dựng. Kiểu được dùng để tuỳ chỉnh bản đồ cơ sở tiêu chuẩn của Google. Tham số styles chỉ hợp lệ nếu loại bản đồ là roadmap. Để biết cú pháp kiểu hoàn chỉnh, hãy xem Tài liệu tham khảo về kiểu.

overlay

Giá trị boolean chỉ định có nên hiển thị layerTypes dưới dạng lớp phủ riêng biệt hay kết hợp với hình ảnh cơ sở. Khi là true, bản đồ cơ sở sẽ không hiển thị. Nếu bạn chưa xác định bất kỳ layerTypes nào, thì giá trị này sẽ bị bỏ qua.

Ví dụ: yêu cầu loại bản đồ satellite có lớp layerRoadmap và overlay được đặt thành false sẽ tạo ra các ô tương đương với loại bản đồ hybrid được dùng trong API JavaScript của Maps (hình ảnh bên trái). Cùng một loại bản đồ và lớp có overlay được đặt thành true sẽ tạo ra một ô trong suốt có lớp phủ bản đồ, được tạo kiểu phù hợp để phủ lên hình ảnh vệ tinh (hình ảnh bên phải).

overlay: false overlay: true
Lớp phủ được đặt thành false Lớp phủ được đặt thành true

JSON sau đây là ví dụ về một nội dung yêu cầu thông thường chứa cả trường bắt buộc và trường không bắt buộc.

{
  "mapType": "satellite",
  "language": "en-US",
  "region": "us",
  "layerTypes": [ "layerRoadmap", "layerStreetview" ],
  "overlay":  true,
  "scale": "scaleFactor1x",
  "styles": [
    {
      "stylers": [
        { "hue": "#00ffe6" },
        { "saturation": -20 }
      ]
    },{
      "featureType": "road",
      "elementType": "geometry",
      "stylers": [
        { "lightness": 100 },
        { "visibility": "simplified" }
      ]
    }
  ]
}

Ví dụ này cung cấp một lớp phủ phù hợp để kết hợp với hình ảnh vệ tinh. Ví dụ này chứa cả lớp phủ bản đồ đường đi và lớp phủ chế độ xem đường phố. Bản đồ kết quả được hiển thị bằng tên và dữ liệu bằng tiếng Anh, như được nói ở Hoa Kỳ.

Phản hồi bằng mã phiên

JSON sau đây là ví dụ về nội dung phản hồi.

{
  "session": "IgAAAHGU9jnAU4KOAfwY3Bcd6eH_WxQsyocSBAdUnAr9pnvTTNXtF9c_27RBo94ytEXTDg",
  "expiry": "1361828036",
  "tileWidth": 256,
  "tileHeight": 256,
  "imageFormat": "png"
}

Danh sách sau đây chứa định nghĩa của các trường trong nội dung phản hồi.

session
Giá trị mã phiên mà bạn phải thêm vào tất cả các yêu cầu Map Tiles API.
expiry
Một chuỗi chứa thời gian (tính bằng giây kể từ thời điểm bắt đầu hệ thống) mà mã thông báo hết hạn. Mã phiên có hiệu lực trong 2 tuần kể từ thời điểm tạo, nhưng chính sách này có thể thay đổi mà không cần thông báo.
tileWidth
Chiều rộng của các ô được đo bằng pixel.
tileHeight
Chiều cao của các ô được đo bằng pixel.
imageFormat
Định dạng hình ảnh, có thể là png hoặc jpeg.