DriveItem のサムネイルを一覧表示する

  • [アーティクル]

名前空間: microsoft.graph

DriveItem リソースの ThumbnailSet リソースのコレクションを取得します。

DriveItem はゼロ以上の ThumbnailSet リソースで表すことができます。 各 thumbnailSet は 1 つ以上のサムネイル オブジェクトを持つことができ、そのオブジェクトはアイテムを表すイメージです。 たとえば、thumbnailSet には 、small、medium など、一般的なlarge オブジェクトが含まれます。

OneDrive 上でサムネイルを操作する方法はたくさんあります。 次に、最も一般的なものを示します。

  • アイテムの利用可能なサムネイルを列挙する
  • アイテムの 1 つのサムネイルを取得する
  • サムネイルのコンテンツを取得する
  • 1 つの要求で複数のアイテムのサムネイルを取得する
  • カスタムのサムネイル サイズを取得する
  • アイテムのカスタム サムネイルをアップロードする
  • カスタムのアップロード済みサムネイルが存在するかどうかを確認する

この API は、次の国内クラウド展開で使用できます。

グローバル サービス 米国政府機関 L4 米国政府機関 L5 (DOD) 21Vianet が運営する中国
✅ ✅ ✅ ✅

アクセス許可

この API の最小特権としてマークされているアクセス許可またはアクセス許可を選択します。 アプリで必要な場合にのみ、より高い特権のアクセス許可またはアクセス許可を使用します。 委任されたアクセス許可とアプリケーションのアクセス許可の詳細については、「 アクセス許可の種類」を参照してください。 これらのアクセス許可の詳細については、 アクセス許可のリファレンスを参照してください。

アクセス許可の種類 最小特権アクセス許可 特権の高いアクセス許可
委任 (職場または学校のアカウント) Files.Read Files.Read.All、Files.ReadWrite、Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All
委任 (個人用 Microsoft アカウント) Files.Read Files.Read.All、Files.ReadWrite、Files.ReadWrite.All
アプリケーション Files.Read.All Files.ReadWrite.All、Sites.Read.All、Sites.ReadWrite.All

HTTP 要求

GET /drives/{drive-id}/items/{item-id}/thumbnails
GET /groups/{group-id}/drive/items/{item-id}/thumbnails
GET /me/drive/items/{item-id}/thumbnails
GET /sites/{site-id}/drive/items/{item-id}/thumbnails
GET /users/{user-id}/drive/items/{item-id}/thumbnails

オプションのクエリ パラメーター

このメソッドは、OData クエリ パラメーターを$selectサポートして応答をカスタマイズします。

さらに、このメソッドでは、元の向き EXIF 値を使用し、クエリ パラメーターを追加して回転を適用せずにサムネイルを originalOrientation=true 取得することもできます。 これは現在、OneDrive 個人用でのみサポートされています。

要求ヘッダー

名前 説明
Authorization ベアラー {token}。 必須です。 認証と承認の詳細については、こちらをご覧ください。

応答

成功した場合、このメソッドは応答本文で 200 OK 応答コードと ThumbnailSet オブジェクトのコレクションを返します。

例

次の例は、現在のユーザーの OneDrive 内のアイテムの使用可能なサムネイルを取得する要求を示しています。

GET /me/drive/items/{item-id}/thumbnails

この要求では、そのアイテムで使用可能な thumbnailSets の配列が返されます。 ドライブにあるすべてのアイテムは、0 個以上のサムネイルを保持できます。

注:select クエリ文字列パラメーターを使用すると、ThumbnailSet で返されるサムネイルのサイズを制御できます。 たとえば、/thumbnails?select=medium では、中サイズのサムネイルのみを取得します。

応答

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "0",
      "small": { "height": 64, "width": 96, "url": "https://sn3302files..."},
      "medium": { "height": 117, "width": 176, "url": "https://sn3302files..."},
      "large": { "height": 533, "width": 800, "url": "https://sn3302files..."}
    }
  ]
}

1 つのサムネイルを取得する

1 つのサムネイルとサイズのメタデータを、要求で直接アドレス指定 (特定して) して取得します。

HTTP 要求

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}

パス パラメーター

名前 型 説明
item-id string 参照されるアイテムの一意識別子。
thumb-id number サムネイルのインデックス (通常 0-4)。 カスタム サムネイルがある場合は、そのインデックスは 0 になります。
size string 要求されるサムネイルのサイズ。 これは、後述する標準サイズか、カスタム サイズのいずれかになります。 
HTTP/1.1 200 OK
Content-Type: application/json

{
  "width": 100,
  "height": 100,
  "url": "https://onedrive.com/asd123a/asdjlkasjdkasdjlk.jpg"
}

サムネイルのバイナリ コンテンツを取得する

サムネイルの content プロパティを要求することにより、サムネイルのコンテンツを直接取得できます。

HTTP 要求

GET /me/drive/items/{item-id}/thumbnails/{thumb-id}/{size}/content

応答

サービスは、サムネイルの URL へのリダイレクトで応答します。

HTTP/1.1 302 Found
Location: https://b0mpua-by3301.files.1drv.com/y23vmagahszhxzlcvhasdhasghasodfi

サムネイル URL はキャッシュ対応です。 この URL は、新しいサムネイルの生成を要求する方法でアイテムを変更する場合に変更されます。

DriveItems を一覧表示する際にサムネイルを取得する

表示する DriveItem リソースのリストを取得する場合、$expand クエリ文字列パラメーターを使用して、それらのリソースのサムネイルも含めることができます。 これによりアプリは、複数の要求を実行することなく、サムネイルとアイテムを 1 つの要求で取得することができます。

HTTP 要求

GET /me/drive/items/{item-id}/children?$expand=thumbnails

応答

サービスは、DriveItems とそのサムネイルのリストで応答します。

HTTP/1.1 200 OK
Content-type: application/json

{
  "value": [
    {
      "id": "182331E8-2788-4932-B52A-A6550577043F",
      "name": "my photo.jpg",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    },
    {
      "id": "2D223953-A56B-4D9B-ADF3-13E7820673A2",
      "name": "presentation.pptx",
      "thumbnails": [
        {
          "small": { "width": 96,
                     "height": 96,
                     "url": "https://sn3302files..."
                   }
        }
      ]
    }
  ]
}

サイズのオプション

次の表で、使用可能なサムネイルのサイズを定義します。 サムネイルの任意のサイズを要求できますが、定義済みの値が存在する可能性が高く、値は即時に返されます。

名前 解像度 縦横比 説明
small 96 longest Original 圧縮率の高い小さなサムネイルは、正方形にトリミングされます。
medium 176 longest Original OneDrive の Web ビューの標準的なアイテムのサイズにトリミングされます。
large 800 longest Original サムネイルの長辺が 800 ピクセルになるよう、サイズ変更されます。
smallSquare 96x96 正方形にトリミング 小さな正方形のサムネイル
mediumSquare 176x176 正方形にトリミング 小さな正方形のサムネイル
largeSquare 800x800 正方形にトリミング 大きな正方形のサムネイル

カスタムのサムネイル サイズを要求する

定義済みのサイズに加えて、アプリでは、先頭に c を付けたサムネイルのディメンション (寸法) を指定することで、カスタムのサムネイル サイズを要求できます。 たとえば、アプリで 300x400 のサムネイルが必要な場合は、そのサイズを次に示すように要求できます。

GET /me/drive/items/{item-id}/thumbnails?select=c300x400_crop

これにより、次に示すように選択したカスタムのサムネイル サイズのみの応答が返されます。

HTTP/1.1 200 OK
Content-Type: application/json

{
  "value": [
    {
      "id": "0",
      "c300x400_crop": { "height": 300, "width": 400, "url": "https://sn3302files.onedrive.com/123"},
    }
  ]
}

要求するサムネイルのサイズの後ろに、次に示すオプションを指定できます。

カスタム識別子の例

サムネイル識別子 解像度 縦横比 説明
c300x400 300x400 のボックスに制限されます Original 300x400 ピクセルのボックスに収まるサムネイルを生成します。縦横比は維持されます。
c300x400_crop 300x400 トリミング 300x400 ピクセルのサムネイルを生成します。 これは、300x400 のボックスに収まるように画像のサイズを変更し、このボックスに収まらない部分をトリミングするように動作します。

注: 返されるサムネイルのピクセル ディメンションは要求されたものと正確に一致しないことがありますが、縦横比は一致します。 サムネイルがすでに存在しており、要求された解像度に簡単に拡大縮小できる場合、要求されたものよりも大きいサムネイルが返されることがあります。

備考

注: OneDrive for Business および SharePoint の場合:

次の呼び出しを使用したサムネイル コレクションの展開は機能しません。

  • GET /drive/root:/{item-path}?expand=children(expand=thumbnails)
  • GET /drive/items/{item-id}/children?expand=thumbnails

サムネイルは、SharePoint Server 2016 ではサポートされていません。

エラー応答

エラーがどのように返されるかについては、「エラー応答」を参照してください。