Parameter sistem

Platform API Google menentukan parameter sistem untuk mengontrol fungsi umum di seluruh REST dan gRPC API, seperti kunci API, mask kolom respons, atribusi kuota, dan pemformatan JSON. Bergantung pada protokolnya, Anda akan meneruskan parameter sistem ke layanan sebagai parameter kueri URL atau header HTTP. Anda dapat menentukan parameter ini secara langsung saat menulis kode kustom, meskipun alat seperti library klien yang disediakan Google menangani banyak di antaranya secara otomatis.

Pemetaan HTTP

Untuk permintaan HTTP, parameter sistem dikirim sebagai parameter kueri URL atau header permintaan HTTP. Misalnya, jika Anda memiliki parameter sistem $foo, parameter tersebut akan dikirim sebagai ?$foo=xxx di URL, atau ?%24foo=xxx jika dienkode URL. Lihat tabel di bawah untuk mengetahui detailnya.

Pemetaan gRPC

Untuk gRPC permintaan, parameter sistem dikirim sebagai header permintaan HTTP dengan kunci dalam huruf kecil. Lihat tabel di bawah untuk mengetahui detailnya.

Definisi

Tabel berikut mencantumkan semua parameter sistem dan definisinya.

Parameter Kueri URL Header HTTP/gRPC Deskripsi
Authorization Kredensial autentikasi. Lihat Ringkasan autentikasi untuk mengetahui detailnya.
$alt,
alt		 Format respons alternatif. Nilai yang didukung adalah json (default), media, proto, sse (streaming JSON).
$apiVersion X-Goog-Api-Version Versi API yang akan digunakan. Tidak semua API mendukung parameter ini: periksa dokumentasi API sebelum menggunakannya.
$.xgafv Format error JSON. Nilai yang didukung adalah 1, 2 (default). Format error 1 hanya boleh digunakan oleh Library Klien Google API.
$callback,
callback		 Parameter callback JSONP.
$ct Content-Type Penggantian header permintaan Content-Type HTTP.
$fields,
fields		 X-Goog-FieldMask FieldMask yang digunakan untuk pemfilteran respons. Jika kosong, semua kolom harus ditampilkan kecuali jika didokumentasikan sebaliknya.
X-HTTP-Method-Override Metode HTTP yang dimaksudkan untuk permintaan. Beberapa proxy jaringan tidak menerima semua metode HTTP.
$key,
key		 X-Goog-Api-Key Kunci Google API. Lihat https://cloud.google.com/docs/authentication/api-keys untuk mengetahui detailnya.
passwd,
password		 Dicadangkan untuk mencegah penempatan sandi di URL.
$prettyPrint,
prettyPrint		 Respons JSON yang diformat. Nilai yang didukung adalah true (default), false.
quotaUser X-Goog-Quota-User ID pengguna semu untuk menagih kuota per pengguna. Jika tidak ditentukan, pokok yang diautentikasi akan digunakan. Jika tidak ada pokok yang diautentikasi, alamat IP klien akan digunakan. Jika ditentukan, kunci API yang valid dengan batasan layanan harus digunakan untuk mengidentifikasi project kuota. Jika tidak, parameter ini akan diabaikan.
$outputDefaults Memaksa untuk menampilkan nilai default proto untuk respons JSON.
$unique Parameter kueri unik untuk menonaktifkan penyimpanan dalam cache permintaan.
X-Goog-Api-Client Identifikasi klien API. Nilainya adalah daftar string NAME "/" SEMVER yang dipisahkan spasi, dengan NAME hanya boleh berisi huruf kecil, digit, dan "-", serta SEMVER harus berupa string versi semantik. Contoh: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0.
X-Goog-Request-Reason Berisi alasan untuk membuat permintaan, yang dimaksudkan untuk dicatat dalam logging audit. Contoh alasannya adalah nomor tiket kasus dukungan. Untuk log audit, karakter dalam alasan menentukan apakah alasan tersebut dienkode base64 sebelum dilampirkan ke entri log. Alasan yang hanya menyertakan huruf, digit, dan spasi akan dipertahankan dalam teks biasa. Alasan yang menyertakan karakter lain akan dienkode base64.
$userProject X-Goog-User-Project Project yang ditentukan pemanggil untuk tujuan kuota dan penagihan. Pemanggil harus memiliki izin serviceusage.services.use pada project.
X-Server-Timeout Batas waktu (dalam detik, nilai float) bagi server untuk menyelesaikan pemrosesan permintaan. Parameter sistem ini hanya berlaku untuk REST API yang tidak berlaku untuk batas waktu sisi klien.
x-goog-request-params Meneruskan parameter tambahan untuk permintaan gRPC. Nilai harus dienkode string kueri URL (misalnya, key1=value1&key2=value2).

Kunci dan nilai tertentu yang didukung dalam header ini bergantung pada layanan dan metode Google API individual yang dipanggil. Tidak ada satu set parameter universal untuk header ini. Selalu lihat dokumentasi untuk API tertentu yang Anda gunakan untuk menentukan parameter mana yang didukung atau diperlukan.

Penggunaan umum mencakup:
  • Informasi Perutean: Untuk layanan regional, header ini sering kali membawa parameter untuk membantu GFE merutekan permintaan ke backend regional yang benar. Hal ini sering kali melibatkan kunci yang cocok dengan bagian nama resource (misalnya, name=projects/my-proj/locations/us-central1, parent=projects/my-proj/locations/us-central1) atau parameter lokasi eksplisit (misalnya, grpc-location=locations/us-central1).
  • Fungsi Khusus API: Misalnya, BigQuery Storage Write API menggunakan parameter write_stream dalam header ini untuk panggilan gRPC multi-region non-AS (misalnya, x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream).
Contoh:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

Log perubahan

  • 2026-10 Dokumentasi yang dipublikasikan untuk X-Goog-Api-Version.
  • 2026-06 Dokumentasi yang diperbarui untuk x-goog-request-params.
  • 2021-11 Dokumentasi yang dipublikasikan untuk x-goog-request-params.
  • 2021-02 Dokumentasi yang dipublikasikan untuk quotaUser.
  • 2020-07 Parameter kueri OAuth 2.0 tidak digunakan lagi.
  • 2019-10 Parameter sistem X-Server-Timeout diperkenalkan.
  • 2017-10 Parameter sistem X-Goog-User-Project diperkenalkan.