Wenn Sie genau die benötigten Felder zurückgeben und die Leistung verbessern möchten, verwenden Sie den Abfrageparameter fields
in Ihrem Methodenaufruf.
Standardmäßig sendet der Server eine Reihe von Feldern zurück, die für die abgefragte Ressource spezifisch sind. Die Methode files.get
gibt beispielsweise nur id
, name
und mimeType
für die Ressource files
zurück. Die Methode permissions.get
gibt andere Standardfelder für eine permissions
-Ressource zurück.
Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den Abfrageparameter fields
enthält, sendet er den Statuscode HTTP 200 OK
zusammen mit den angeforderten Daten zurück. Wenn der Abfrageparameter „fields“ einen Fehler enthält oder ungültig ist, gibt der Server den Statuscode HTTP 400 Bad Request
zusammen mit einer Fehlermeldung zurück, die angibt, was bei der Feldauswahl nicht stimmt. Beispielsweise gibt files.list(fields='files(id,capabilities,canAddChildren)')
den Fehler „Ungültige Feldauswahl kannAddChildren“ zurück. Der richtige Abfrageparameter für Felder in diesem Beispiel ist files.list(fields='files(id,capabilities/canAddChildren)')
.
Informationen zum Ermitteln der Felder, die Sie mit dem Parameter fields
zurückgeben können, finden Sie auf der Dokumentationsseite der abgefragten Ressource. Informationen dazu, welche Felder für eine Datei zurückgegeben werden können, finden Sie in der Dokumentation zur Ressource files
.
Formatierungsregeln für Feldparameter
Das Format des Werts des Feldanfrageparameters basiert grob auf der XPath-Syntax. Nachfolgend finden Sie Formatierungsregeln für den Parameter fields
. Alle diese Regeln verwenden Beispiele in Bezug auf die Methode files.get
.
Verwenden Sie eine durch Kommas getrennte Liste, um mehrere Felder auszuwählen, z. B.
'name, mimeType'
.Verwenden Sie
a/b
, um das Feldb
auszuwählen, das im Felda
verschachtelt ist, z. B.'capabilities/canDownload'
. Weitere Informationen finden Sie unter Felder einer verschachtelten Ressource abrufen.Verwenden Sie eine untergeordnete Auswahl, um eine Reihe bestimmter Unterfelder von Arrays oder Objekten anzufordern, indem Sie Ausdrücke in Klammern „()“ setzen.
'permissions(id)'
gibt beispielsweise nur die Berechtigungs-ID für jedes Element im Berechtigungsarray zurück.Wenn alle Felder in einem Objekt zurückgegeben werden sollen, verwenden Sie bei der Feldauswahl ein Sternchen als Platzhalter. Mit
'permissions/permissionDetails/*'
werden beispielsweise alle verfügbaren Berechtigungsdetailfelder pro Berechtigung ausgewählt. Die Verwendung dieses Platzhalters kann negative Auswirkungen auf die Leistung der Anfrage haben.
Beispiel ansehen
Anfrage
In diesem Beispiel stellen wir den Datei-ID-Pfadparameter und mehrere Felder als Abfrageparameter in der Anfrage bereit. In der Antwort werden die Feldwerte für die Datei-ID zurückgegeben.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared
Antwort
{ "name": "File1", "starred": false, "shared": true } }
Felder einer verschachtelten Ressource abrufen
Wenn ein Feld auf eine andere Ressource verweist, können Sie angeben, welche Felder der verschachtelten Ressource abgerufen werden sollen.
Wenn Sie beispielsweise das Feld role
(verschachtelte Ressource) der Ressource permissions
verwenden möchten, verwenden Sie eine der folgenden Optionen:
permissions.get
mitfields=role
oderfields=*
.files.get
mitfields=permissions(role)
oderfields=permissions/role
.files.get
mitfields=permissions
, um alle Felder der verschachtelten Ressource zu implizieren.changes.list
mitfields=changes(file(permissions(role)))
.
Wenn Sie mehrere Felder abrufen möchten, verwenden Sie eine durch Kommas getrennte Liste. Beispiel: files.list
mit fields=files(id,name,createdTime,modifiedTime,size)
.
Beispiel ansehen
Anfrage
In diesem Beispiel stellen wir den Datei-ID-Pfadparameter und mehrere Felder, einschließlich bestimmter Felder der verschachtelten Berechtigungsressource, als Abfrageparameter in der Anfrage bereit. In der Antwort werden die Feldwerte für die Datei-ID zurückgegeben.
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=name,starred,shared,permissions(kind,type,role)
Antwort
{ "name": "File1", "starred": false, "shared": true, "permissions": [ { "kind": "drive#permission", "type": "user", "role": "owner" } ] }