このドキュメントでは、ファイルの名前付けと、インデックス登録可能なテキストやサムネイルなどのメタデータの操作に関する重要な考慮事項について説明します。ファイルを挿入して取得するには、
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 には、2 つの制限付きメタデータ スコープがあります。drive.metadata
と drive.metadata.readonly です。drive.metadata スコープを使用すると、ファイルのメタデータを表示して
管理できますが、drive.metadata.readonly は読み取り専用です。どちらもファイル コンテンツへのアクセスを厳しく禁止しています。詳細については、Choose
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 ドキュメント、スプレッドシート、スライドなど、多くの一般的なファイル形式のサムネイルを自動的に生成します。 サムネイルを使用すると、ユーザーはドライブ ファイルをより簡単に識別できます。
ドライブが標準のサムネイルを生成できないファイル形式の場合は、アプリケーションで生成されたサムネイル画像を提供できます。ファイルの作成または更新時に、
contentHints.thumbnail フィールドを files リソースに設定してサムネイルをアップロードします。
詳細:
contentHints.thumbnail.imageフィールドを、URL とファイル名セーフな Base64 エンコードされた画像に設定します（RFC 4648 のセクション 5を参照）。contentHints.thumbnail.mimeTypeフィールドを、サムネイルの適切な MIME タイプに設定します。
ドライブがファイルからサムネイルを生成できる場合は、自動的に生成されたサムネイルが使用され、アップロードしたサムネイルは無視されます。サムネイルを生成できない場合は、提供したサムネイルが使用されます。
サムネイルは次のルールに準拠する必要があります。
- PNG、GIF、JPG 形式でアップロードできます。
- 推奨される幅は 1,600 ピクセルです。
- 最小幅は 220 ピクセルです。
- 最大ファイルサイズは 2 MB です。
- 保存するたびにアプリケーションで更新する必要があります。
詳細については、files リソースをご覧ください。
サムネイルを取得する
ドライブ ファイルのメタデータ（サムネイルを含む）を取得できます。
サムネイル情報は、
thumbnailLink フィールドの
files リソースに格納されます。
特定のサムネイルを返す
次のコードサンプルは、特定のファイルの 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)