このドキュメントでは、ファイルの命名と、インデックス登録可能なテキストやサムネイルなどのメタデータの操作に関する重要な考慮事項について説明します。ファイルを挿入して取得するには、files リソースをご覧ください。
ファイル名と拡張子を指定する
Google Drive API を使用してファイルを挿入する場合は、タイトル プロパティにファイル拡張子を指定する必要があります。たとえば、JPEG ファイルを挿入するオペレーションでは、メタデータに "name": "cat.jpg" のようなものを指定する必要があります。
後続の GET レスポンスには、name プロパティで最初に指定された拡張機能が入力された読み取り専用 fileExtension プロパティを含めることができます。Google ドライブのユーザーがファイルのダウンロードをリクエストした場合、または同期クライアントからファイルがダウンロードされた場合、ドライブはタイトルに基づいて完全なファイル名（拡張子付き）を作成します。拡張子がない場合、ドライブはファイルの MIME タイプに基づいて拡張子を判断しようとします。
インデックス登録可能なテキストを保存する
ドライブは、テキスト ドキュメント、PDF、テキストを含む画像など、一般的なファイル形式を認識すると、検索用にドキュメントを自動的にインデックスに登録します。アプリが他の種類のファイル（描画、動画、ショートカットなど）を保存する場合は、ファイルの contentHints.indexableText フィールドにインデックス登録可能なテキストを指定することで、検出可能性を高めることができます。
インデックス登録可能なテキストは HTML としてインデックス化されます。インデックス登録可能なテキスト文字列 <section attribute="value1">Here's some text</section> を保存すると、「Here's some text」はインデックスに登録されますが、「value1」は登録されません。そのため、インデックス登録可能なテキストとして XML を保存することは、HTML を保存するほど有用ではありません。
indexableText を指定する際は、次の点にも注意してください。
contentHints.indexableTextのサイズの上限は 128 KB です。- ユーザーが検索すると予想される主な用語と概念をキャプチャします。
- インデックス エンジンが効率的に重要度順に並べ替えるため、テキストを重要度順に並べ替えようとしないでください。
- アプリは、保存するたびにインデックス登録可能なテキストを更新する必要があります。
- テキストがファイルのコンテンツまたはメタデータに関連していることを確認します。
この最後のポイントは当たり前のように思えますが、重要です。検索結果にファイルを強制的に表示するために、よく検索される用語を追加することはおすすめしません。これにより、ユーザーはイライラし、ファイルを削除する動機になる可能性があります。
サムネイルをアップロードする
ドライブでは、Google ドキュメント、スプレッドシート、スライドなど、多くの一般的なファイル形式のサムネイルが自動的に生成されます。サムネイルは、ユーザーがドライブ ファイルをより簡単に識別できるようにします。
ドライブで標準のサムネイルを生成できないファイル形式の場合は、アプリケーションで生成されたサムネイル画像を指定できます。ファイルの作成または更新時に、files リソースの contentHints.thumbnail フィールドを設定してサムネイルをアップロードします。
詳細は以下のとおりです。
contentHints.thumbnail.imageフィールドを、URL セーフおよびファイル名セーフの base64 エンコードされた画像に設定します（RFC 4648 セクション 5 を参照）。contentHints.thumbnail.mimeTypeフィールドを、サムネイルに適した MIME タイプに設定します。
ドライブがファイルからサムネイルを生成できる場合は、自動生成されたサムネイルが使用され、アップロードされたサムネイルは無視されます。サムネイルを生成できない場合は、指定したサムネイルが使用されます。
サムネイルは次のルールに準拠している必要があります。
- PNG、GIF、JPG 形式でアップロードできます。
- 推奨される幅は 1,600 ピクセルです。
- 最小幅は 220 ピクセルです。
- 最大ファイルサイズは 2 MB です。
- 保存するたびにアプリによって更新される必要があります。
詳細については、files リソースをご覧ください。
サムネイルを取得する
ドライブ ファイルのメタデータ（サムネイルなど）を取得できます。サムネイル情報は、files リソースの thumbnailLink フィールドに格納されます。
特定のサムネイルを返す
次のコードサンプルは、クエリ パラメータとして複数のフィールドを指定して特定のファイルの thumbnailLink メタデータを返す files.get メソッド リクエストを示しています。詳細については、ファイルの特定のフィールドを返すをご覧ください。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID は、検索するファイルの fileId に置き換えます。
利用可能な場合は、ファイルのサムネイルへの有効期間の短い URL が返されます。通常、リンクは数時間有効です。このフィールドは、リクエスト元のアプリがファイルのコンテンツにアクセスできる場合にのみ入力されます。ファイルが一般公開されていない場合は、thumbnailLink で返された URL を認証情報リクエストを使用して取得する必要があります。
サムネイルのリストを返す
次のコードサンプルは、複数のフィールドをクエリ パラメータとして使用した files.list メソッド リクエストを示しています。このリクエストは、ファイルのリストの thumbnailLink メタデータを返します。詳細については、ファイルとフォルダを検索するをご覧ください。
GET https://www.googleapis.com/drive/v3/files/?fields=files(id,name,mimeType,thumbnailLink)
検索結果を特定のファイル形式に制限するには、クエリ文字列を適用して MIME タイプを設定します。たとえば、次のコードサンプルは、リストを Google スプレッドシート ファイルに制限する方法を示しています。MIME タイプの詳細については、 Google Workspace と Google ドライブでサポートされている MIME タイプをご覧ください。
GET https://www.googleapis.com/drive/v3/files/q=mimeType='application/vnd.google-apps.spreadsheet'&fields=files(id,name,mimeType,thumbnailLink)