Bestimmte Felder zurückgeben

In diesem Dokument wird erläutert, wie Sie den Parameter fields in Google Drive verwenden.

Wenn Sie genau die Felder zurückgeben möchten, die Sie benötigen, und die Leistung verbessern möchten, verwenden Sie den fields System parameter in Ihrem Methodenaufruf.

Informationen zu anderen Systemparametern, die für die Drive API gelten, finden Sie unter Alternative Systemparameter.

Funktionsweise des Parameters „fields“

Der fields Parameter verwendet eine FieldMask für die Antwortfilterung. Feldmasken werden verwendet, um eine Teilmenge von Feldern anzugeben, die von einer Anfrage zurückgegeben werden sollen. Mit Feldmasken lässt sich verhindern, dass unnötige Daten angefordert werden, was wiederum hilft, unnötige Verarbeitungszeiten zu vermeiden.

Wenn Sie den Parameter fields nicht angeben, gibt der Server eine Standardgruppe von Feldern zurück, die für die Methode spezifisch sind. Beispielsweise gibt die list Methode für die files Methode nur die Felder kind, id, name und mimeType zurück. Die get Methode für die permissions Ressource gibt eine andere Gruppe von Standardfeldern zurück.

Für alle Methoden der Ressourcen about, comments (außer delete) und replies (außer delete) müssen Sie den fields Parameter festlegen. Diese Methoden geben keine Standardgruppe von Feldern zurück.

Nachdem ein Server eine gültige Anfrage verarbeitet hat, die den Parameter fields enthält, gibt er den Statuscode HTTP 200 OK zusammen mit den angeforderten Daten zurück. Wenn der Parameter „fields“ einen Fehler enthält oder ungültig ist, gibt der Server den Statuscode HTTP 400 Bad Request zusammen mit einer Fehlermeldung zurück, in der angegeben wird, was bei Ihrer Feldauswahl falsch ist. Beispielsweise files.list(fields='files(id,capabilities,canAddChildren)') führt zu einem Fehler mit der Meldung „Invalid field selection canAddChildren.“ Der richtige Parameter „fields“ für dieses Beispiel ist files.list(fields='files(id,capabilities/canAddChildren)').

Auf der Dokumentationsseite der Ressource, die Sie abfragen, finden Sie die Felder, die Sie mit dem Parameter fields zurückgeben können. Informationen dazu, welche Felder Sie für eine Datei zurückgeben können, finden Sie in der Dokumentation zur Ressource files. Weitere dateispezifische Suchbegriffe finden Sie unter Suchbegriffe und Operatoren.

Regeln für das Format von Feldparametern

Das Format des Werts des Anfrageparameters „fields“ basiert grob auf der XPath-Syntax. Im Folgenden finden Sie Formatierungsregeln für den Parameter fields. Alle diese Regeln verwenden Beispiele im Zusammenhang mit der Methode files.get.

Mit einer durch Kommas getrennten Liste können Sie mehrere Felder auswählen, z. B. 'name, mimeType'.
Verwenden Sie a/b, um das Feld b auszuwählen, das im Feld a verschachtelt ist, z. B. 'capabilities/canDownload'. Weitere Informationen finden Sie unter Felder einer verschachtelten Ressource abrufen.
Verwenden Sie ein untergeordnetes Auswahlzeichen, um eine Reihe von untergeordneten Feldern von Arrays oder Objekten anzufordern. Setzen Sie dazu Ausdrücke in Klammern: „()“. Beispiel: 'permissions(id)' gibt nur die Berechtigungs-ID für jedes Element im Array „permissions“ zurück.
Wenn Sie alle Felder in einem Objekt zurückgeben möchten, verwenden Sie ein Sternchen (*) als Platzhalter in der Feldauswahl. Beispiel: 'permissions/permissionDetails/*' wählt alle verfügbaren Felder für Berechtigungsdetails pro Berechtigung aus. Die Verwendung des Platzhalters kann sich negativ auf die Leistung der Anfrage auswirken.

Ersuchen

In diesem Beispiel geben wir den Pfadparameter für die Datei-ID und mehrere Felder als Abfrageparameter in der Anfrage an. Die Antwort gibt die Feldwerte für die Datei-ID zurück.

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 abrufen möchten, verwenden Sie eine der folgenden Optionen:

permissions.get mit fields=role.
permissions.get mit fields=*, um alle Felder von permissions anzuzeigen.
files.get mit fields=permissions(role) oder fields=permissions/role.
files.get mit fields=permissions, um alle Felder von permissions anzuzeigen.
changes.list mit fields=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).

Ersuchen

In diesem Beispiel geben wir den Pfadparameter für die Datei-ID und mehrere Felder, einschließlich bestimmter Felder der verschachtelten Ressource „permissions“, als Abfrageparameter in der Anfrage an. Die Antwort gibt die Feldwerte für die Datei-ID zurück.

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"
    }
  ]
}

Alternative Systemparameter

Abfrageparameter, die für alle Google Drive API-Vorgänge gelten, sind unter Systemparameter dokumentiert.