Dateimetadaten verwalten

In diesem Dokument werden wichtige Überlegungen zur Benennung von Dateien und zum Umgang mit Metadaten wie indexierbaren Text und Miniaturansichten erläutert. Informationen zum Einfügen und Abrufen von Dateien finden Sie in der Ressource files.

Dateinamen und -erweiterungen angeben

Bei Anwendungen sollte beim Einfügen von Dateien über die Google Drive API eine Dateiendung in der Eigenschaft "title" angegeben werden. Beim Vorgang zum Einfügen einer JPEG-Datei sollte beispielsweise in den Metadaten "name": "cat.jpg" angegeben werden.

Die nachfolgenden GET-Antworten können das schreibgeschützte Attribut fileExtension enthalten, für das die Erweiterung verwendet wird, die ursprünglich in der Eigenschaft name angegeben wurde. Wenn ein Google Drive-Nutzer den Download einer Datei anfordert oder wenn die Datei über den Synchronisierungsclient heruntergeladen wird, erstellt Drive basierend auf dem Titel einen vollständigen Dateinamen (mit Erweiterung). Wenn die Erweiterung fehlt, versucht Drive, die Erweiterung anhand des MIME-Typs der Datei zu bestimmen.

Indexierbaren Text speichern

Drive indexiert Dokumente automatisch für die Suche, wenn der Dateityp erkannt wird. Dazu gehören Textdokumente, PDFs, Bilder mit Text und andere gängige Typen. Falls Ihre Anwendung andere Dateitypen speichert, z. B. Zeichnungen, Videos und Verknüpfungen, können Sie die Auffindbarkeit verbessern, indem Sie in das Feld contentHints.indexableText der Datei indexierten Text eingeben.

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, „Wert1“ jedoch nicht. Aus diesem Grund ist das Speichern von XML als indexierbaren Text nicht so nützlich wie das Speichern von HTML.

Bei der Angabe von indexableText ist außerdem Folgendes zu beachten:

  • Die Größenbeschränkung für contentHints.indexableText beträgt 128 KB.
  • Erfassen Sie die Schlüsselbegriffe und -konzepte, nach denen Nutzer suchen müssen.
  • Versuchen Sie nicht, Text nach Wichtigkeit zu sortieren, da dies von der Indexierung effizient ausgeführt wird.
  • Ihre Anwendung sollte den indexierbaren Text bei jedem Speichervorgang aktualisieren.
  • Achten Sie darauf, dass sich der Text auf den Inhalt oder die Metadaten der Datei bezieht.

Dieser letzte Punkt mag offensichtlich erscheinen, aber er ist wichtig. Es ist nicht ratsam, häufig gesuchte Begriffe hinzuzufügen, damit eine Datei in den Suchergebnissen erscheint. Das kann Nutzer frustrieren und sogar dazu bewegen, die Datei zu löschen.

Miniaturansichten hochladen

Drive erstellt automatisch Miniaturansichten für viele gängige Dateitypen wie Google Docs, Google Tabellen und Google Präsentationen. Anhand der Miniaturansichten können Nutzer Drive-Dateien leichter erkennen.

Für Dateitypen, für die Drive keine Standard-Miniaturansicht generieren kann, können Sie eine von Ihrer Anwendung generierte Miniaturansicht bereitstellen. Laden Sie beim Erstellen oder Aktualisieren einer Datei eine Miniaturansicht hoch. Legen Sie dazu das Feld contentHints.thumbnail in der Ressource files fest.

Insbesondere:

  • Legen Sie im Feld contentHints.thumbnail.image die URL und den Dateinamen für ein base64-codiertes Bild fest (siehe RFC 4648, Abschnitt 5).
  • Legen Sie im Feld contentHints.thumbnail.mimeType den entsprechenden MIME-Typ für die Miniaturansicht fest.

Wenn Drive eine Miniaturansicht aus der Datei generieren kann, verwendet es die automatisch generierte und ignoriert diejenigen, die Sie möglicherweise hochgeladen haben. Wenn keine Miniaturansicht generiert werden kann, wird die von Ihnen angegebene verwendet.

Für Thumbnails gelten folgende Regeln:

  • 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 von Ihrer Anwendung bei jedem Speichern aktualisiert werden.

Weitere Informationen finden Sie in der Ressource files.

Miniaturansichten abrufen

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

Bestimmte Miniaturansicht zurückgeben

Das folgende Codebeispiel zeigt eine Anfrage für die Methode files.get 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 finden möchten.

Sofern verfügbar, gibt die Anfrage eine kurzlebige URL zur Miniaturansicht der Datei zurück. In der Regel ist der Link mehrere Stunden lang gültig. Das Feld wird nur gefüllt, wenn die anfragende App Zugriff auf den Dateiinhalt hat. Wenn die Datei nicht öffentlich freigegeben wird, muss die in thumbnailLink zurückgegebene URL über eine Anfrage mit Anmeldedaten abgerufen werden.

Liste mit Miniaturansichten zurückgeben

Das folgende Codebeispiel zeigt eine Anfrage für die Methode files.list mit mehreren Feldern als Abfrageparameter, um die thumbnailLink-Metadaten für eine Liste von Dateien zurückzugeben. Weitere Informationen finden Sie unter Nach Dateien und Ordnern 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. Das folgende Codebeispiel zeigt, wie Sie die Liste auf Google Tabellen-Dateien beschränken können. 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)