このドキュメントでは、ファイルに名前を付ける場合や、インデックス登録可能なテキストやサムネイルなどのメタデータを操作する際の重要な考慮事項について説明します。ファイルの挿入と取得については、files リソースをご覧ください。
ファイル名と拡張子を指定する
Google Drive API を使用してファイルを挿入するときは、アプリが title プロパティでファイル拡張子を指定する必要があります。たとえば、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 フィールドに格納されます。
特定のサムネイルを返す
次のコードサンプルは、クエリ パラメータとして複数のフィールドを持つ files.get メソッド リクエストを示し、特定のファイルの thumbnailLink メタデータを返します。詳細については、ファイルの特定のフィールドを返すをご覧ください。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID は、検索するファイルの fileId に置き換えます。
有効であれば、リクエストはファイルのサムネイルへの有効期間の短い URL を返します。通常、このリンクは数時間有効です。このフィールドは、リクエスト元のアプリがファイルのコンテンツにアクセスできる場合にのみ入力されます。ファイルが一般公開で共有されていない場合は、認証済みリクエストを使用して thumbnailLink で返される URL を取得する必要があります。
サムネイルのリストを返す
次のコードサンプルは、ファイルリストの thumbnailLink メタデータを返すクエリ パラメータとして複数のフィールドを持つ files.list メソッド リクエストを示しています。詳細については、ファイルとフォルダを検索するをご覧ください。
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)