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. Die Methode list für die Ressource files gibt beispielsweise 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, approvals, comments (außer delete) und replies (außer delete) müssen Sie den Parameter fields 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 mit Ihrer Feldauswahl nicht stimmt. For example, 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)').

Informationen zu den Feldern, die Sie mit dem Parameter fields zurückgeben können, finden Sie auf der Dokumentationsseite der Ressource, die Sie abfragen. 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 des Feldparameters

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.

  • Sie können keine einzelnen Elemente einer Map auswählen, wenn ihre Schlüssel Sonderzeichen enthalten (z. B. Schrägstriche / oder Punkte .). Wenn Sie beispielsweise versuchen, einen bestimmten Schlüssel für das Exportformat in exportLinks mit fields=exportLinks/application/pdf auszuwählen, wird ein Fehler HTTP 400 Bad Request zurückgegeben, da der Pfadparser / als Trennzeichen für verschachtelte Eigenschaften interpretiert. Wenn Sie Schlüssel/Wert-Paare mit Sonderzeichen in den Schlüsseln abrufen möchten, fordern Sie die gesamte Map an (z. B. fields=exportLinks) und filtern Sie die Ergebnisse clientseitig.

Anfrage

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).

Verwenden Sie verschachtelte Klammern, um verschachtelte Felder in verschachtelten Arrays oder Objekten anzugeben. Beispiel: Wenn Sie Dateien mit ihrer ID, ihrem Namen und den Details des verschachtelten Inhabers (Anzeigename und E‑Mail-Adresse) auflisten und gleichzeitig das Token für die nächste Seite für die Paginierung abrufen möchten, verwenden Sie files.list mit fields=nextPageToken,files(id,name,owners(displayName,emailAddress)).

Anfrage

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.