Dateimetadaten verwalten

In diesem Dokument werden wichtige Aspekte für die Benennung von Dateien und die Arbeit mit Metadaten wie indexierbarem Text und Thumbnails behandelt. Informationen zum Einfügen und Abrufen von Dateien finden Sie in der files-Ressource.

Übersicht über Metadaten

In der Google Drive API stellt die files-Ressource die Metadaten dar. Im Gegensatz zu APIs, bei denen Metadaten ein Unterobjekt sind, wird in der Drive API die gesamte files-Ressource als Metadaten behandelt. Sie können direkt über die Methoden get oder list für die Ressource files auf die Metadaten zugreifen.

Standardmäßig geben die Methoden get und list nur einen Teilsatz von Feldern zurück. Wenn Sie bestimmte Daten abrufen möchten, müssen Sie den fields-Systemparameter in Ihrer Anfrage definieren. Wird dieser Parameter weggelassen, gibt der Server eine Standarduntermenge von Feldern zurück, die für die Methode spezifisch ist. Die Methode list gibt beispielsweise nur die Felder kind, id, name, mimeType und resourceKey für jede Datei zurück. Informationen zum Zurückgeben anderer Felder finden Sie unter Bestimmte Felder zurückgeben.

Außerdem hängt die Sichtbarkeit von Metadaten von der Rolle des Nutzers für die Datei ab. Mit der permissions-Ressource werden nicht die zulässigen Aktionen eines Nutzers für eine Datei oder einen Ordner festgelegt. Stattdessen enthält die files-Ressource eine Sammlung von booleschen capabilities-Feldern. Die Google Drive API leitet diese capabilities aus der permissions-Ressource ab, die der Datei oder dem Ordner zugeordnet ist. Weitere Informationen finden Sie unter Dateifunktionen.

Die Drive API bietet zwei eingeschränkte Metadatenbereiche: drive.metadata und drive.metadata.readonly. Mit dem Bereich drive.metadata können Sie Dateimetadaten ansehen und verwalten, während drive.metadata.readonly schreibgeschützt ist. Beide verbieten den Zugriff auf Dateiinhalte strikt. Weitere Informationen finden Sie unter Google Drive API-Bereiche auswählen.

Prüfen Sie zum Schluss immer Ihre Logik in Bezug auf Berechtigungen und Bereiche. Ein Nutzer ist beispielsweise Eigentümer einer Datei mit vollständigen Berechtigungen, aber die Drive API blockiert Versuche, die Datei zu ändern oder herunterzuladen, wenn Ihre App nur den Bereich drive.metadata.readonly hat.

Dateinamen und ‑erweiterungen angeben

Apps sollten beim Einfügen von Dateien mit der Google Drive API eine Dateiendung im Attribut name angeben. Bei einem Vorgang zum Einfügen einer JPEG-Datei sollte in den Metadaten beispielsweise "name": "cat.jpg" angegeben werden.

Nachfolgende GET-Antworten können das schreibgeschützte Attribut fileExtension enthalten, das mit der Erweiterung gefüllt ist, die ursprünglich im Attribut name angegeben wurde. Wenn ein Google Drive-Nutzer eine Datei herunterlädt oder die Datei über den Synchronisierungsclient heruntergeladen wird, erstellt Drive anhand des Namens einen vollständigen Dateinamen (mit Erweiterung). Wenn die Erweiterung fehlt, versucht Drive, sie anhand des MIME-Typs der Datei zu ermitteln.

Indexierbaren Text speichern

Drive indexiert Dokumente automatisch für die Suche, wenn der Dateityp erkannt wird, z. B. Textdokumente, PDFs, Bilder mit Text und andere gängige Typen. Wenn Ihre App andere Dateitypen speichert, z. B. Zeichnungen, Videos und Verknüpfungen, können Sie die Auffindbarkeit verbessern, indem Sie indexierbaren Text im Feld contentHints.indexableText der Datei angeben.

Indexierbarer Text wird als HTML indexiert. Wenn Sie den indexierbaren Textstring <section attribute="value1">Here's some text</section> speichern, wird „Hier ist etwas Text“ indexiert, „value1“ jedoch nicht. Daher ist das Speichern von XML als indexierbarer Text nicht so nützlich wie das Speichern von HTML.

Beachten Sie beim Angeben von indexableText Folgendes:

  • Die Größenbeschränkung für contentHints.indexableText beträgt 128 KB.
  • Erfassen Sie die wichtigsten Begriffe und Konzepte, nach denen ein Nutzer Ihrer Meinung nach suchen wird.
  • Versuchen Sie nicht, Text nach Wichtigkeit zu sortieren, da der Indexer dies effizient für Sie erledigt.
  • Ihre Anwendung sollte den indexierbaren Text bei jedem Speichern aktualisieren.
  • Der Text muss sich auf den Inhalt oder die Metadaten der Datei beziehen.

Dieser letzte Punkt mag offensichtlich erscheinen, ist aber wichtig. Es ist keine gute Idee, häufig gesuchte Begriffe hinzuzufügen, um zu erzwingen, dass eine Datei in den Suchergebnissen angezeigt wird. Das kann Nutzer frustrieren und sie sogar dazu veranlassen, die Datei zu löschen.

Thumbnails hochladen

In Drive werden automatisch Miniaturansichten für viele gängige Dateitypen wie Google-Dokumente, -Tabellen und -Präsentationen generiert. Thumbnails helfen Nutzern, Drive-Dateien besser zu erkennen.

Für Dateitypen, für die in Drive keine Standardminiaturansicht generiert werden kann, können Sie ein von Ihrer Anwendung generiertes Miniaturbild bereitstellen. Laden Sie beim Erstellen oder Aktualisieren einer Datei ein Miniaturbild hoch, indem Sie das Feld contentHints.thumbnail in der files-Ressource festlegen.

Im Detail:

  • Legen Sie das Feld contentHints.thumbnail.image auf das URL- und Dateiname-sichere base64-codierte Bild fest (siehe RFC 4648, Abschnitt 5).
  • Legen Sie für das Feld contentHints.thumbnail.mimeType den entsprechenden MIME-Typ für das Vorschaubild fest.

Wenn in Drive ein Vorschaubild aus der Datei generiert werden kann, wird das automatisch generierte Vorschaubild verwendet und alle von Ihnen hochgeladenen Vorschaubilder werden ignoriert. Wenn keine Miniaturansicht generiert werden kann, wird die von Ihnen bereitgestellte verwendet.

Thumbnails sollten diesen Regeln entsprechen:

  • Sie können im PNG-, GIF- oder JPG-Format hochgeladen werden.
  • Die empfohlene Breite beträgt 1.600 Pixel.
  • Die Mindestbreite beträgt 220 Pixel.
  • Die maximale Dateigröße beträgt 2 MB.
  • Sie sollten bei jedem Speichern von Ihrer Anwendung aktualisiert werden.

Weitere Informationen finden Sie in der Ressource files.

Thumbnails abrufen

Sie können Metadaten, einschließlich Thumbnails, für Drive-Dateien abrufen. Informationen zu Miniaturansichten befinden sich im Feld thumbnailLink der Ressource files.

Ein bestimmtes Thumbnail zurückgeben

Das folgende Codebeispiel zeigt eine get-Methodenanfrage mit mehreren Feldern als Abfrageparameter, um die thumbnailLink-Metadaten für eine bestimmte Datei zurückzugeben. Weitere Informationen finden Sie unter Bestimmte Felder für eine Datei zurückgeben.

GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink

Ersetzen Sie FILE_ID durch den fileId der Datei, die Sie suchen.

Falls verfügbar, wird in der Antwort eine kurzlebige URL zur Miniaturansicht der Datei zurückgegeben. Der Link ist in der Regel mehrere Stunden lang gültig. Das Feld wird nur ausgefüllt, wenn die anfragende App auf den Inhalt der Datei zugreifen kann. Wenn die Datei nicht öffentlich freigegeben ist, muss die in thumbnailLink zurückgegebene URL mit einer Anfrage mit Anmeldedaten abgerufen werden.

Eine Liste von Thumbnails zurückgeben

Das folgende Codebeispiel zeigt eine list-Methodenanfrage mit mehreren Feldern als Abfrageparameter, um die thumbnailLink-Metadaten für eine Liste von Dateien zurückzugeben. Weitere Informationen finden Sie unter Dateien und Ordner suchen.

GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)

Wenn Sie die Suchergebnisse auf einen bestimmten Dateityp beschränken möchten, wenden Sie einen Abfragestring an, um den MIME-Typ festzulegen. Im folgenden Codebeispiel wird gezeigt, wie Sie die Liste auf Google-Tabellen beschränken. Weitere Informationen zu MIME-Typen finden Sie unter Von Google Workspace und Google Drive unterstützte MIME-Typen.

GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)