このドキュメントでは、ファイル名や、インデックス登録可能なテキストやサムネイルなどのメタデータの操作に関する重要な考慮事項について説明します。ファイルの挿入と取得については、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 フィールドに格納されます。
特定のサムネイルを返す
次のコードサンプルは、複数のフィールドをクエリ パラメータとして指定した files.get メソッド リクエストを示しています。このリクエストは、特定のファイルの thumbnailLink メタデータを返します。詳しくは、ファイルの特定のフィールドを返すをご覧ください。
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)