Memilih informasi yang akan ditampilkan

Saat Anda memanggil metode untuk mengomputasi rute atau matriks rute, Anda harus menentukan informasi apa yang Anda inginkan dengan mencantumkan bidang-bidang untuk kembali dalam respons. Tidak ada daftar default untuk kolom yang ditampilkan. Jika Anda menghilangkan daftar ini, metode akan menampilkan error.

Anda menentukan daftar kolom dengan membuat mask kolom respons. Anda kemudian lulus mask kolom respons ke salah satu metode dengan menggunakan parameter URL $fields atau fields, atau dengan menggunakan header HTTP atau gRPC X-Goog-FieldMask.

Menggunakan mask kolom adalah praktik desain yang baik untuk memastikan bahwa Anda tidak meminta data yang tidak perlu, yang akan membantu menghindari waktu pemrosesan yang tidak perlu dan biaya yang ditagih.

Untuk informasi selengkapnya tentang parameter URL, lihat Parameter Sistem.

Menentukan mask kolom respons

Mask kolom respons adalah daftar jalur yang dipisahkan koma, di mana setiap menentukan kolom unik dalam pesan respons. Jalur dimulai dari pesan respons tingkat atas dan menggunakan jalur yang dipisahkan titik ke kolom yang ditentukan.

Buat dan tentukan jalur kolom sebagai berikut:

  1. Temukan kolom berisi informasi yang Anda butuhkan dari Routes API. Untuk mengetahui detailnya, lihat Referensi Kolom.
  2. Menentukan jalur untuk kolom yang Anda perlukan dan membuat mask kolom untuk kolom tersebut: Untuk mengetahui detailnya, lihat Menentukan mask kolom yang ingin Anda gunakan.

  3. Gabungkan mask kolom untuk semua kolom yang Anda perlukan, yang memisahkan mask kolom dengan koma. Misalnya, untuk meminta distanceMeters untuk segmen rute, ditambah durasi untuk setiap langkah segmen rute, masukkan keduanya, dipisahkan dengan koma, tanpa spasi:

    routes.legs.distanceMeters,routes.legs.steps.duration

  4. Kirim mask kolom dengan permintaan API Anda. Misalnya, dalam permintaan cURL, Anda akan menentukan mask kolom dengan -H dan X-Goog-FieldMask:

    -H X-Goog-FieldMask: routes.legs.distanceMeters,routes.legs.steps.duration
Untuk mengetahui contoh dan detail selengkapnya, lihat bagian berikut.

Referensi Kolom

Untuk melihat kolom yang dapat Anda minta sebagai respons melalui mask kolom, lihat referensi Routes API yang ditautkan dalam daftar berikut. Tentukan kolom dalam camel case seperti yang ditunjukkan dalam referensi. Misalnya, routePreference.

Referensi ini mencakup kolom yang tersedia; Namun, Anda harus merujuk pada hierarki kolom untuk menentukan jalur mask kolom lengkap. Untuk mengetahui detail tentang cara mendapatkan hierarki kolom, lihat Menentukan mask kolom yang ingin Anda gunakan.

  • Mask kolom rute komputasi
    • REST: Menentukan kolom Route di yang akan ditampilkan, misalnya, diawali dengan routes., routes.distanceMeters.
    • gRPC: Menentukan kolom Route di yang akan ditampilkan.
  • Menghitung mask kolom matriks rute

Menentukan mask kolom yang akan digunakan

Berikut cara menentukan kolom mana yang ingin Anda gunakan, dan membuat mask kolom untuk kolom tersebut:

  1. Minta semua kolom menggunakan mask kolom *.
  2. Lihat hierarki kolom dalam respons untuk {i>field<i} yang Anda inginkan.

  3. Buat mask kolom Anda menggunakan hierarki kolom yang ditunjukkan di langkah sebelumnya, menggunakan format ini:

    topLevelField[.secondLevelField][.thirdLevelField][...]

Misalnya, untuk respons parsial dari rute ini:

"routes": [
    {
        "legs": [
            {  "steps": [
                    {"distanceMeters": 119},
                    {"distanceMeters": 41}  ]
            }
        ],
        "distanceMeters": 160
    }
]

Jika Anda hanya ingin menampilkan kolom distanceMeters untuk segmen rute; yaitu, distanceMeters terakhir dalam contoh sebelumnya, mask kolom Anda adalah sebagai berikut:

routes.legs.distanceMeters

Jika Anda ingin menampilkan kolom distanceMeters untuk setiap langkah segmen rute; yaitu, distanceMeters pada steps dalam contoh sebelumnya, mask kolom Anda adalah sebagai berikut:

routes.legs.steps.distanceMeters

Jika Anda ingin menampilkan keduanya, dengan hasil di atas, mask kolom Anda adalah sebagai berikut:

routes.legs.distanceMeters,routes.legs.steps.distanceMeters

Contoh jalur mask kolom

Bagian ini berisi contoh lainnya tentang cara menentukan jalur kolom sebagai bagian dari mask kolom respons dalam panggilan REST dan gRPC.

Panggilan REST ke computeRoutes

Pada contoh pertama, Anda menggunakan panggilan REST ke Metode computeRoutes untuk menghitung rute. Dalam contoh ini, di header, Anda menentukan mask kolom untuk menampilkan kolom rute distanceMeters dan duration dalam respons. Jangan lupa untuk mengawali nama kolom dengan routes.

X-Goog-FieldMask: routes.distanceMeters,routes.duration

Panggilan REST ke computeRouteMatrix

Untuk REST computeRouteMatrix yang digunakan untuk menghitung matriks rute, pada header, tentukan untuk mengembalikan originIndex, destinationIndex, dan duration untuk setiap kombinasi origin dan tujuan:

X-Goog-FieldMask: originIndex,destinationIndex,duration

Panggilan gRPC

Untuk gRPC, tetapkan variabel yang berisi mask kolom respons. Selanjutnya, Anda dapat meneruskan variabel tersebut ke permintaan.

const (
  fieldMask = "routes.distanceMeters,routes.duration,routes.polyline.encodedPolyline"
)

Pertimbangan jalur kolom

Hanya sertakan kolom yang Anda butuhkan dalam respons untuk menampilkan hanya yang Anda perlukan:

  • Mengurangi waktu pemrosesan, sehingga hasil yang ditampilkan dengan latensi lebih rendah.
  • Memastikan performa latensi stabil. Jika Anda memilih semua kolom, atau jika memilih semua kolom di tingkat teratas, Anda mungkin mengalami penurunan kinerja ketika isian baru ditambahkan dan kemudian secara otomatis disertakan dalam jawaban Anda.
  • Menghasilkan ukuran respons yang lebih kecil, yang berarti throughput jaringan yang lebih tinggi.
  • Memastikan Anda tidak meminta data yang tidak perlu, untuk menghindari waktu pemrosesan yang tidak perlu dan tagihan yang tidak perlu.

Untuk detail selengkapnya tentang membuat mask kolom, lihat metode field_mask.proto.

Meminta token rute

Untuk meminta agar Routes API menampilkan token rute untuk rute yang dihasilkan, ikuti langkah-langkah berikut:

  1. Tetapkan parameter yang diperlukan untuk menampilkan token rute:
    • Tetapkan travelMode ke DRIVE.
    • Tetapkan routingPreference ke TRAFFIC_AWARE atau TRAFFIC_AWARE_OPTIMAL.
  2. Pastikan tidak ada titik jalan rute yang merupakan titik jalan via.
  3. Tentukan mask kolom routes.routeToken untuk menampilkan token rute: 
    X-Goog-FieldMask: routes.routeToken

Anda dapat menggunakan token rute untuk rute yang direncanakan di Navigation SDK. Untuk detail selengkapnya, lihat Merencanakan rute (Android) atau Rencanakan rute (iOS).

Contoh token rute

Berikut adalah contoh isi permintaan cURL untuk satu tempat asal dan tujuan tunggal rute, menggunakan mask kolom untuk meminta token rute, bersama dengan rute durasi, jarak, dan polyline rute:

curl -X POST -d
{"origin":{
    "location": {
        "latLng":{
            "latitude":  -37.8167,
            "longitude": 144.9619
        }
    }
},
"destination":{
    "location": {
        "latLng":{
            "latitude":-37.8155,
            "longitude": 144.9663
        }
    }
},
"routingPreference":"TRAFFIC_AWARE",
"travelMode":"DRIVE"
}
-H 'X-Goog-Api-Key: YOUR_API_KEY' \
-H X-Goog-FieldMask: routes.routeToken,routes.duration,routes.distanceMeters,routes.polyline.encodedPolyline
'https://routes.googleapis.com/directions/v2:computeRoutes'

Untuk mengetahui detail selengkapnya, lihat Referensi Compute Routes API.