Mã thông báo phiên là một phần dữ liệu (UUID) được dùng trong lệnh gọi REST để xác định một phiên – một loạt các lượt trao đổi thông báo có liên quan. Bạn phải đưa mã phiên vào tất cả các yêu cầu về Thẻ thông tin 2D và hình ảnh trong Chế độ xem đường phố.
Bạn bao gồm thông số này dưới dạng giá trị của thông số session
được thêm vào tất cả các URL yêu cầu.
Trong API Thẻ thông tin của bản đồ, mã thông báo 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 chuyển một tập hợp tuỳ chọn hiển thị với từng yêu cầu thẻ thông tin. Bạn có thể sử dụng cùng một mã phiên trên nhiều ứng dụng.
Mã thông báo phiên hiện có hiệu lực trong vòng 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ã thông báo phiên bằng cách xem trường expiry
trong thông báo phản hồi.
Yêu cầu mã thông báo phiên
Để yêu cầu mã thông báo phiên, hãy gửi yêu cầu POST qua HTTPS đế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 đồ sơn trên Google Maps tiêu chuẩn.
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 đưa vào loại lớplayerRoadmap
(được mô tả trong phần Trường không bắt buộc). 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 Thẻ thông tin trong Chế độ xem đường phố.
language
Thẻ ngôn ngữ IEEETF chỉ định ngôn ngữ dùng để hiển thị thông tin trên thẻ thông tin. Ví dụ:
en-US
chỉ định tiếng Anh là ngôn ngữ được sử dụng ở Hoa Kỳ.region
Mã nhận dạng khu vực Common Locale Data Repository (Kho lưu trữ dữ liệu ngôn ngữ 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 không bắt buộc
imageFormat
- Chỉ định định dạng tệp cần trả về. Giá trị hợp lệ là
jpeg
hoặcpng
. Tệp JPEG không hỗ trợ độ trong suốt, do đó, bạn không nên dùng tệp này cho ô lớp phủ. Nếu bạn không chỉ địnhimageFormat
, thì định dạng phù hợp nhất cho thẻ thông tin sẽ tự động được chọn. scale
Tăng 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 bao phủ 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 đồ, nhờ đó giảm sự lộn xộn. Các giá trị sau là giá trị
scale
hợp lệ:scaleFactor1x
: Mặc định.scaleFactor2x
: Tăng gấp đôi kích thước nhãn và xoá các nhãn tính năng nhỏ.scaleFactor4x
: Tăng gấp bốn kích thước nhãn và xoá các nhãn tính năng nhỏ.
Các ví dụ sau đây minh hoạ hiệu quả 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 |
---|---|
highDpi
- Chỉ định xem có trả về các thẻ thông tin có độ phân giải cao hay không. Nếu hệ số tỷ lệ tăng,
highDpi
sẽ được dùng để tăng kích thước của thẻ thông tin. Thông thường, việc tăng hệ số tỷ lệ sẽ mở rộng thẻ thông tin thu được thành một hình ảnh có cùng kích thước, qua đó làm giảm chất lượng. VớihighDpi
, kích thước thu được cũng tăng lên, duy trì chất lượng. DPI là viết tắt của Dots per Inch, còn DPI cao có nghĩa là thẻ thông tin sẽ hiển thị nhiều điểm ảnh hơn trên mỗi inch so với bình thường. Nếu làtrue
, thì số 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). Phạm vi bao phủ của thẻ thông tin 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. Tính năng này không ảnh hưởng đến các thẻ thông tin có tỷ lệ 1x.
Hệ số tỷ lệ 1x | Hệ số tỷ lệ DPI cao 2x |
---|---|
layerTypes
Một mảng các giá trị chỉ định kiểu 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ể tuỳ ý phủ lên loại bản đồsatellite
. Không ảnh hưởng đến thẻ thông tin lộ trình. layerStreetview
- Hiển thị các đường phố và vị trí có hỗ trợ Chế độ xem đường phố bằng cách sử dụng các đường viền màu xanh dương trên bản đồ.
layerTraffic
- Cho thấy 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 giao diện và cấp độ chi tiết của các đối tượng bản đồ, chẳng hạn như đường, công viên và các khu vực đã xây dựng. Tạo 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 đầy đủ, hãy xem phần Tham chiếu kiểu.overlay
Giá trị boolean chỉ định xem
layerTypes
nên được hiển thị dưới dạng một lớp phủ riêng biệt hay kết hợp với hình ảnh cơ sở. Khitrue
, bản đồ cơ sở sẽ không hiển thị. Nếu bạn chưa xác địnhlayerTypes
nào, thì giá trị này sẽ bị bỏ qua.
Ví dụ: việc yêu cầu một loại bản đồ satellite
có lớp layerRoadmap
và overlay
được đặt thành false
sẽ dẫn đến các ô tương đương với loại bản đồ hybrid
dùng trong API JavaScript của Maps (hình ảnh bên trái). Các kiểu bản đồ và lớp tương tự có overlay
được đặt thành true
sẽ tạo ra một thẻ thông tin trong suốt với 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 : sai |
overlay : đúng |
---|---|
JSON sau đây là một ví dụ về nội dung yêu cầu điển hình chứa cả trường bắt buộc và 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ộ trình và lớp phủ chế độ xem phố. Bản đồ thu được sẽ được hiển thị cùng với tên và dữ liệu bằng tiếng Anh, như được nói ở Hoa Kỳ.
apiOptions
: Một mảng giá trị chỉ định các tuỳ chọn bổ sung để áp dụng.
Sau đây là các tuỳ chọn được hỗ trợ:
MCYJ5E517XR2JC
– Chọn sử dụng kiểu bản đồ mới. Trong thời gian chọn sử dụng, các yêu cầu của bạn sẽ nhận được kiểu hiện có trừ phi giá trị này được chỉ định.
Phản hồi mã thông báo phiên
JSON sau đây là một nội dung phản hồi mẫu.
{
"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 hoạt động mà bạn phải đưa vào tất cả các yêu cầu API Thẻ thông tin bản đồ.
expiry
- Một chuỗi chứa thời gian (tính bằng giây kể từ thời gian bắt đầu của hệ thống) mà mã thông báo hết hạn. Mã thông báo phiên có hiệu lực trong vòng 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ó 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ặcjpeg
.