Systemparameter

Die API-Plattform von Google definiert Systemparameter, um allgemeine Funktionen in REST- und gRPC-APIs zu steuern, z. B. API-Schlüssel, Feldmasken für Antworten, Kontingentzuweisung und JSON-Formatierung. Je nach Protokoll übergeben Sie Systemparameter als URL-Abfrageparameter oder HTTP-Header an einen Dienst. Sie können diese Parameter direkt angeben, wenn Sie benutzerdefinierten Code schreiben. Tools wie die von Google bereitgestellten Clientbibliotheken verarbeiten jedoch viele von ihnen automatisch.

HTTP-Zuordnung

Bei HTTP-Anfragen werden Systemparameter als URL-Abfrageparameter oder HTTP-Anfrageheader gesendet. Wenn Sie beispielsweise den Systemparameter $foo haben, wird dieser in der URL als ?$foo=xxx oder URL-codiert als ?%24foo=xxx gesendet. Weitere Details finden Sie in der nachfolgenden Tabelle.

gRPC-Zuordnung

Für gRPC-Anfragen werden Systemparameter als HTTP -Anfrageheader mit Schlüsseln in Kleinbuchstaben gesendet. Weitere Details finden Sie in der Tabelle unten.

Definitionen

In der folgenden Tabelle sind alle Systemparameter und deren Definitionen aufgelistet.

URL-Abfrageparameter HTTP-/gRPC-Header Beschreibung
Authorization Authentifizierungsdaten Weitere Informationen finden Sie unter Authentifizierung.
$alt,
alt		 Alternatives Antwortformat. Unterstützte Werte: json (Standard), media, proto, sse (JSON-Streams).
$apiVersion X-Goog-Api-Version Die zu verwendende API-Version. Nicht alle APIs unterstützen diesen Parameter. Prüfen Sie vor der Verwendung die API-Dokumentation.
$.xgafv JSON-Fehlerformat. Unterstützte Werte: 1, 2 (Standard). Das Fehlerformat 1 sollte nur von Google API-Clientbibliotheken verwendet werden.
$callback,
callback		 JSONP-Callback-Parameter
$ct Content-Type Überschreibt den HTTP-Content-Type-Anfrageheader.
$fields,
fields		 X-Goog-FieldMask FieldMask, das für die Antwortfilterung verwendet wird. Wenn leer, sollten alle Felder zurückgegeben werden, sofern nicht anders angegeben.
X-HTTP-Method-Override Die beabsichtigte HTTP-Methode für die Anfrage. Einige Netzwerkproxys akzeptieren nicht alle HTTP-Methoden.
$key,
key		 X-Goog-Api-Key Google API-Schlüssel. Weitere Informationen finden Sie unter https://cloud.google.com/docs/authentication/api-keys.
passwd,
password		 Reserviert, um das Einfügen von Passwörtern in URLs zu verhindern.
$prettyPrint,
prettyPrint		 Optimierte Darstellung der JSON-Antwort. Unterstützte Werte: true (Standard), false.
quotaUser X-Goog-Quota-User Eine Pseudo-Nutzer-ID für die Abrechnung von Kontingenten pro Nutzer. Wenn nicht angegeben, wird das authentifizierte Hauptkonto verwendet. Wenn kein authentifiziertes Hauptkonto vorhanden ist, wird die Client-IP-Adresse verwendet. Wenn angegeben, muss ein gültiger API-Schlüssel mit Dienstbeschränkungen verwendet werden, um das Kontingentprojekt zu identifizieren. Andernfalls wird dieser Parameter ignoriert.
$outputDefaults Erzwingt die Ausgabe von Proto-Standardwerten für JSON-Antworten.
$unique Eindeutiger Abfrageparameter zum Deaktivieren des Anfrage-Cachings.
X-Goog-Api-Client API-Client-ID. Der Wert ist eine durch Leerzeichen getrennte Liste von NAME "/" SEMVER-Strings, wobei NAME nur Kleinbuchstaben, Ziffern und "-" enthalten und SEMVER ein semantischer Versionsstring sein sollte. Beispiel: X-Goog-Api-Client: python/3.5.0 grpc-google-pubsub-v1/0.1.0-beta2 linux/2.7.0.
X-Goog-Request-Reason Enthält einen Grund für die Anfrage, der im Audit-Log aufgezeichnet werden soll. Ein Grund ist beispielsweise die Ticketnummer eines Supportfalls. Bei Audit-Logs bestimmen die Zeichen im Grund, ob der Grund Base64-codiert wird, bevor er an den Logeintrag angehängt wird. Gründe, die nur Buchstaben, Ziffern und Leerzeichen enthalten, bleiben im Nur-Text erhalten. Gründe, die andere Zeichen enthalten, werden Base64-codiert.
$userProject X-Goog-User-Project Ein vom Aufrufer für Kontingent- und Abrechnungszwecke angegebenes Projekt. Der Aufrufer muss die Berechtigung serviceusage.services.use für das Projekt haben.
X-Server-Timeout Zeitlimit (in Sekunden, Float-Wert) für den Server, um die Verarbeitung der Anfrage abzuschließen Dieser Systemparameter gilt nur für REST APIs, für die kein clientseitiges Zeitlimit zutreffend ist.
x-goog-request-params Zusätzliche Parameter für gRPC-Anfragen übergeben. Der Wert muss als URL-Abfragestring codiert sein (z.B. key1=value1&key2=value2).

Die spezifischen Schlüssel und Werte, die in diesem Header unterstützt werden, hängen vom jeweiligen Google API-Dienst und der aufgerufenen Methode ab. Es gibt keine einheitliche, universelle Gruppe von Parametern für diesen Header. In der Dokumentation der jeweiligen API, mit der Sie interagieren, erfahren Sie, welche Parameter unterstützt oder erforderlich sind.

Häufige Anwendungsfälle:
  • Routing-Informationen:Bei regionalisierten Diensten enthält dieser Header häufig Parameter, mit denen GFEs die Anfrage an das richtige regionale Backend weiterleiten können. Dabei werden häufig Schlüssel verwendet, die mit Teilen des Ressourcennamens übereinstimmen (z.B. name=projects/my-proj/locations/us-central1, parent=projects/my-proj/locations/us-central1) oder explizite Standortparameter (z.B. grpc-location=locations/us-central1).
  • API-spezifische Funktionen: Die BigQuery Storage Write API verwendet beispielsweise den write_stream Parameter in diesem Header für gRPC-Aufrufe in mehreren Regionen außerhalb der USA (z.B. x-goog-request-params: write_stream=projects/myproject/datasets/myds/tables/mytable/streams/mystream).
Beispiel:
x-goog-request-params: name=projects/my-project/locations/us-central1&foo=bar

Änderungsprotokoll

  • 2026-10 Dokumentation für X-Goog-Api-Version veröffentlicht.
  • 2026-06 Dokumentation für x-goog-request-params aktualisiert.
  • 2021-11 Dokumentation für x-goog-request-params veröffentlicht.
  • 2021-02 Dokumentation für quotaUser veröffentlicht.
  • 2020-07 OAuth 2.0-Abfrageparameter veröffentlicht.
  • 2019-10 Systemparameter X-Server-Timeout eingeführt.
  • 2017-10 Systemparameter X-Goog-User-Project eingeführt.