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

名前空間: microsoft.graph

重要

Microsoft Graph の /beta バージョンの API は変更される可能性があります。 実稼働アプリケーションでこれらの API を使用することは、サポートされていません。 v1.0 で API を使用できるかどうかを確認するには、Version セレクターを使用します。

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

0 個以上の thumbnailSet リソースは、driveItem を表すことができます。 各 thumbnailSet は 1 つ以上のサムネイル オブジェクトを持つことができ、そのオブジェクトはアイテムを表すイメージです。 たとえば、thumbnailSet には smallmedium など、一般的な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

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

このメソッドは、応答をカスタマイズするために $selectOData クエリ パラメーター をサポートします。

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

応答

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

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

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

アイテムで使用可能な thumbnailSet の配列を 返します。 ドライブにあるすべてのアイテムは、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 ではサムネイルはサポートされていません。

エラー応答

エラーの返し方の詳細については、「エラー応答」を参照してください。