このドキュメントでは、ファイルの名前付けと、インデックス登録可能なテキストやサムネイルなどのメタデータの取り扱いに関する重要な考慮事項について説明します。ファイルの挿入と取得については、files リソースをご覧ください。
ファイル名と拡張子を指定する
Google Drive API を使用してファイルを挿入する場合、アプリはタイトル プロパティでファイル拡張子を指定する必要があります。たとえば、JPEG ファイルを挿入するオペレーションでは、メタデータに "name": "cat.jpg" などを指定する必要があります。
後続の GET レスポンスには、読み取り専用の fileExtension プロパティを含めることができます。このプロパティには、name プロパティで最初に指定された拡張機能が設定されます。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)