Systemparameter

Die API-Plattform von Google bietet eine Reihe gängiger Funktionen für alle auf der Plattform basierenden Google APIs. Um diese Funktionen nutzen und steuern zu können, wurde auf der Plattform eine spezielle Reihe von Anfrageparametern vordefiniert, die als Systemparameter bezeichnet werden. Diese Parameter sind für alle Google REST APIs und gRPC APIs verfügbar. Ein Systemparameter kann entweder mithilfe eines HTTP-Abfrageparameters oder eines HTTP-Headers angegeben werden. Für Google gRPC APIs werden nur HTTP-Header unterstützt.

Die meisten Nutzer müssen diese Parameter nicht direkt verwenden. Sie werden jedoch häufig von Google-Clientbibliotheken verwendet. Wenn Sie benutzerdefinierten Code für den direkten Zugriff auf Google APIs schreiben möchten, können die Systemparameter nützlich sein, um die JSON-Darstellung zu optimieren oder API-Schlüssel anzugeben.

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 Anmeldedaten für die Authentifizierung Weitere Informationen finden Sie unter Authentifizierung.
$alt,
alt		 Alternatives Antwortformat. Unterstützte Werte: json (Standard), media, proto, sse (JSON-Streams).
$.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 für die Anfrage vorgesehene HTTP-Methode. Nicht alle Netzwerk-Proxys akzeptieren 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 Pseudonutzerkennzeichnung für die Abrechnung pro Nutzerkontingenten. 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.
$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 gilt.
x-goog-request-params Zusätzliche Parameter für gRPC-Anfragen im URL-Abfrageformat übergeben. Beispiel: x-goog-request-params: service=pubsub.googleapis.com&release=2021-11-01r0.

Änderungslog

  • 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 X-Server-Timeout-Systemparameter eingeführt.
  • 2017-10 X-Goog-User-Project-Systemparameter eingeführt.