このドキュメントでは、ファイルの名前付けと、インデックス可能なテキストやサムネイルなどのメタデータの取り扱いに関する重要な考慮事項について説明します。ファイルの挿入と取得については、files リソースをご覧ください。
メタデータの概要
Google Drive API では、files リソースはメタデータを表します。メタデータがサブオブジェクトである API とは異なり、Drive API では files リソース全体がメタデータとして扱われます。メタデータには、files リソースの get メソッドまたは list メソッドを使用して直接アクセスできます。
デフォルトでは、get メソッドと list メソッドはフィールドのサブセットのみを返します。特定のデータを取得するには、リクエストで fields システム パラメータを定義する必要があります。省略すると、サーバーはメソッドに固有のフィールドのデフォルトのサブセットを返します。たとえば、list メソッドは、各ファイルの kind、id、name、mimeType、resourceKey フィールドのみを返します。別のフィールドを返すには、特定のフィールドを返すをご覧ください。
また、メタデータの可視性は、ファイルに対するユーザーのロールによって異なります。permissions リソースは、ファイルまたはフォルダに対するユーザーの許可されたアクションを決定しません。代わりに、files リソースにはブール値の capabilities フィールドのコレクションが含まれます。Google Drive API は、ファイルまたはフォルダに関連付けられた permissions リソースからこれらの capabilities を取得します。詳しくは、ファイルの機能についてをご覧ください。
Drive API には、drive.metadata と drive.metadata.readonly という 2 つの制限付きメタデータ スコープがあります。drive.metadata スコープでは、ファイル メタデータの表示と管理ができますが、drive.metadata.readonly は読み取り専用です。どちらもファイル コンテンツへのアクセスを厳しく禁止します。詳細については、Google Drive API のスコープを選択するをご覧ください。
最後に、権限とスコープに関するロジックを必ず検証してください。たとえば、ユーザーがフル権限を持つファイルを所有していても、アプリに drive.metadata.readonly スコープしかない場合、Drive API はファイルの変更やダウンロードの試行をブロックします。
ファイル名と拡張子を指定する
Google Drive API を使用してファイルを挿入する場合、アプリは name プロパティでファイル拡張子を指定する必要があります。たとえば、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 メタデータを返すためのクエリ パラメータとして複数のフィールドを含む get メソッド リクエストを示しています。詳細については、ファイルの特定のフィールドを返すをご覧ください。
GET https://www.googleapis.com/drive/v3/files/FILE_ID?fields=id,name,mimeType,thumbnailLink
FILE_ID は、検索するファイルの fileId に置き換えます。
利用可能な場合、リクエストはファイルのサムネイルへの短期間の URL を返します。通常、リンクは数時間有効です。このフィールドは、リクエスト元のアプリがファイルのコンテンツにアクセスできる場合にのみ入力されます。ファイルが一般公開されていない場合、thumbnailLink で返される URL は認証情報付きリクエストを使用して取得する必要があります。
サムネイルのリストを返す
次のコードサンプルは、複数のフィールドをクエリ パラメータとして使用して、ファイルのリストの thumbnailLink メタデータを返す 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)