OneDrive ファイルピッカー SDK for JavaScript v7.2 を使用してファイルを開く

[アーティクル]
04/08/2023

次のチュートリアルでは、ファイルピッカー SDK をクライアント側の JavaScript アプリケーションに統合する方法を示します。

1. アプリケーションを登録する

OneDrive ピッカーを使用するには、[Azure アプリ登録] ページでアプリケーションを登録し、アプリケーション ID を受け取る必要があります。また、ピッカーを使用して、Web アプリケーションの有効なリダイレクト URI を追加する必要もあります。これは、ピッカー SDK をホストするページ、または自分で定義したカスタム URL のどちらかになります。詳細については、「セットアップする」を参照してください。

2. SDK への参照を追加する

OneDrive JavaScript SDK をページに埋め込みます。

<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>

3. ファイルピッカーを起動する

OneDrive からファイルを開くには、OneDrive ファイルピッカーをプログラムで開始するためのボタンをアプリに用意する必要があります。このコードはブラウザーでポップアップウィンドウを起動するため、明示的なユーザー操作の一環として呼び出すことで、ポップアップブロックでブロックされないようにする必要があります。

OneDrive.open(...) メソッドの一部として、options オブジェクトによって、ピッカーの動作方法とピッカーがコードをコールバックする方法を指定します。

<script type="text/javascript">
  function launchOneDrivePicker(){
    var odOptions = { /* ... specify the desired options ... */ };
    OneDrive.open(odOptions);
  }
</script>
<button onClick="launchOneDrivePicker()">Open from OneDrive</button>

メモ: OneDrive のピッカーが開かれると、ページを含む新しいウィンドウが開きます。SDK はクエリ文字列を使用して、ウィンドウをピッカーにリダイレクトします。ロード時に SDK がページに表示されていない場合 (たとえば、ユーザーの操作に応答して遅延ロードされている場合) は、ピッカーが正しく開かない可能性があります。ユーザーの操作なしで SDK をロードするページにポップアップをリダイレクトするには、redirectUri詳細オプションを使用することをお勧めします。

ピッカーのオプション

ファイルピッカーの動作方法は、ピッカーの動作を制御するパラメーターを含むオブジェクトを指定することで指定できます。このオブジェクトには、ファイルピッカーの完了時またはエラーの発生時に応じたコールバック関数も含まれています。

ファイルピッカーオプションの例

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: true,
  advanced: {},
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

パラメーター

パラメーター名	説明
clientId	統合用にアプリ登録コンソールで生成したアプリケーション ID。
action	選択したファイルに実行するアクションの種類。共有可能な URL の生成、`download`ファイルのコンテンツをダウンロードする有効期間の短い URL の受信、または `query` Microsoft Graph APIまたは OneDrive API で使用できる識別子の取得を指定`share`できます。
multiSelect	既定値は false です。この場合は、ユーザーに 1 つのファイルのみの選択を要求します。true にすると、ユーザーは複数のファイルを選択できるようになります。
viewType	選択できる項目の種類です。既定値は `files` です。 `folders` を指定して、選択範囲をフォルダーのみに制限する、または `all` を指定して、ファイルとフォルダー両方を選択することができます。
accountSwitchEnabled	既定値は `true`、ホストされているファイルピッカーのページに [アカウントの切り替え] UI を表示します。
advanced	ピッカーの動作を詳細にカスタマイズできる追加プロパティのコレクション。ただし、ほとんどのシナリオで必要になることはありません。詳細については、「詳細オプション」を参照してください。
success	ユーザーがファイルのピッキングを完了して、選択したファイルのコレクションを含んでいる response オブジェクトを受け取ったときに呼び出されます。これは、openInNewWindow が `true` の場合に必須です。
cancel	ユーザーがピッカーをキャンセルした場合に呼び出されます。この関数にパラメーターはありません。
error	サーバーでエラーが発生した場合、またはユーザーが選択したファイルへのリンクを取得するためのアクセス許可を持たない場合に呼び出されます。この関数は、1 つのパラメーター (エラーオブジェクト) を受け取ります。

アクションの種類

ピッカーの action パラメーターを使用すると、ユーザーがファイルやフォルダーを選択した後で返される URL の種類を指定できます。有効な値は次のとおりです。

値	説明
`download`	選択したファイルに対するファイルの ID、名前および短期間有効なダウンロード URL を返します。
`share`	選択したファイルに対する読み取り専用の共有 URL を返します。この URL は、別のユーザーと共有できます。
`query`	選択したファイルのメタデータのみを返します。 API を使用して、ファイルに応じた追加のアクションを実行します。

4. ピッカーの response オブジェクトを処理する

ユーザーがファイルのピッキングを完了すると、success コールバックは response オブジェクトを受け取ります。このオブジェクトには、アイテムのプロパティのサブセットを持つ Item リソースのコレクションである value プロパティが含まれています。

{
  "value": [
    {
      "id": "123456",
      "name": "document1.docx",
      "size": 12340,
      "@microsoft.graph.downloadUrl": "https://contoso-my.sharepoint.com/download.aspx?guid=1231231231a",
      "webUrl": "https://cotoso-my.sharepoint.com/personal/user_contoso_com/documents/document1.docx",
      "thumbnails": [
        {
          "id": "0",
          "small": { "url": "https://sn3302files.onedrive.live.com/..." },
          "medium": { "url": "https://sn3302files.onedrive.live.com/..." },
          "large": { "url": "https://sn3302files.onedrive.live.com/..." }
        }
      ]
    }
  ],
  "accessToken": "ey...",
  "apiEndpoint": "https://graph.microsoft.com"
}

response のプロパティ

プロパティ名	種類	説明
value	driveItems の配列	選択されていたファイルに関するメタデータ。
webUrl	URL	OneDrive 個人用アカウントからの複数の選択シナリオの場合に返されます。
accessToken	string	アプリケーションのためにファイルピッカーが受け取ったアクセストークン。これは、余計な認証フローを必要とすることなく、Microsoft Graph に追加の要求を送信するために使用できます。
apiEndpoint	URL	accessToken を使用できる API エンドポイント。

高度なオプション

このピッカーは、追加の高度なシナリオもサポートしています。これにより、ピッカーは高度なシナリオを実現するために OneDrive API と同時に使用できるようになります。

options オブジェクトの高度なパラメーターには、次に示す定義済みのプロパティがあります。

パラメーター名	説明	シナリオ
queryParameters	OneDrive API で指定されたものと同じように、アイテムが返される方法を定義する追加のクエリパラメーターのセット。これには、一般に select 値や expand 値が含まれます。	ファイルまたはフォルダーを照会する
createLinkParameters	共有アクションのリンクを生成するために使用されるパラメーターを変更します。	ファイルを共有する
filter	特定の種類のみを表示するために適用されるファイルの種類のセット。システムの種類の 'photo' および 'folder' と、任意の拡張子 ('.docx' など) のカスタムの種類がサポートされています。たとえば、各フィルターが `,` で区切られている "folder,.png" というフィルター設定は適用可能です。	ファイルを表示する
redirectUri	既定では、ピッカーは認証のリダイレクト URI として、そのピッカーが起動されたページを使用します。これが望ましくないシナリオもあるため、その代わりに使用するカスタム URL を設定できます。この URL はアプリの登録ポータルでリダイレクト URL として登録されている必要があります。ターゲットページは、呼び出し元のページと同じ方法で OneDrive ピッカー SDK を参照する必要があります。	OAuth
endpointHint	エンドポイントヒントは、アプリが通信する OneDrive API エンドポイントに基づいて、SDK でアプリを正しい OAuth エンドポイントにリダイレクトする際に使用されます。 OneDrive API エンドポイントには、OneDrive 個人用、OneDrive for Business または SharePoint Online が含まれます。 `endpointHint` の値は、OneDrive 個人用の場合は `api.onedrive.com` になります。 OneDrive for Business URL または SharePoint ドキュメントライブラリ URL の場合は、 `https://contoso-my.sharepoint.com/personal/foo_contoso_onmicrosoft_com/` や `https://contoso.sharepoint.com/shared%20documents/` などになります。アプリが Microsoft Graph API と通信する場合は不要です。	OAuth
accessToken	OneDrive 個人用、OneDrive for Business、または SharePoint Online の OneDrive API エンドポイントへのアクセス権が付与された accessToken が渡されることがあり、迅速なエクスペリエンスを提供するために OAuth フローをスキップします。 accessToken が提示される場合、`endpointHint` は必須です。	OAuth
loginHint	ユーザーが既にアプリケーションにログインしている場合は、シングルサインオンを有効にする loginHint の値を提供できます。	OAuth
isConsumerAccount	Microsoft Graph API と通信するときに `loginHint` が指定されている場合、SDK ではログインしているユーザーがコンシューマーアカウント (別称: Microsoft アカウント) かビジネスアカウントかを通知することも必要になります。	OAuth
scopes	この SDK は、オープンフローの場合は自動的に `Files.Read.All` スコープを要求し、保存フローの場合は `Files.ReadWrite.All` スコープを要求します。ただし、追加のアクセス許可を要求する場合は、ここに別のスコープを追加できます。	OAuth
navigation	ピッカー SDK 7.2 には、複数の構成を設定でいる新しいピッカー UI が導入されています。すべての構成は、`navigation` オブジェクトを参照してください。	ピッカー UI

注: 現時点では、フィルターの種類の 'photo' は、OneDrive 個人用アカウントでのみサポートされています。

ピッカーと API を併用する

action 値の query と高度なオブジェクトの queryParameters の設定を併用すると、選択したオブジェクトに関するプロパティのカスタムセットを API から返すことができるようになります。たとえば、あるファイルが選択されたときに、写真の詳細 (使用可能な場合) を含めるには、次のようにします。

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  multiSelect: false,
  advanced: {
    queryParameters: "select=id,name,size,file,folder,photo,@microsoft.graph.downloadUrl",
    filter: "folder,.png" /* display folder and files with extension '.png' only */
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

これにより、id、name、size、file、folder、および photo のプロパティを応答で選択するように、ピッカー SDK に指示します。

会社共有可能な読み取り/書き込みリンクを返す

既定では、OneDrive ファイルピッカーは、action が share に設定されているときに表示専用の共有 URL を返します。ただし、createLinkParameters プロパティを使用して、createLink アクションに渡されるパラメーターを変更することができます。

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "share",
  multiSelect: false,
  advanced: {
    createLinkParameters: { type: "edit", scope: "organization" }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

カスタムリダイレクト URI を使用する

アプリが大規模なクライアント側の JavaScript アプリの場合や、状態を維持するためにクエリ文字列パラメーターを使用する場合は、ファイルピッカーを起動したページをリダイレクト URI として使用することが望ましくない場合があります。これには、ポップアップウィンドウ内でアプリ全体の再読み込みが必要になり、パフォーマンスの問題が発生する可能性があります。高度なオブジェクトを通じて、その代わりに使用する代替のリダイレクト URI を指定することができます。

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    redirectUri: "https://contoso.com/filePickerRedirect.htm"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

代替 API エンドポイントを使用する

Microsoft Graph API は、OneDrive 個人用、OneDrive for Business、および SharePoint Online に保管されたファイルへの統合されたアクセスを提供しています。ただし、いくつかの限定的なシナリオでは、Microsoft Graph の代わりに特定の SharePoint サイト URL の使用が必要になることがあります。

この場合、アプリでは Microsoft Graph API エンドポイントの代わりに SharePoint サイトの OneDrive API エンドポイントを指定できます。 OneDrive ピッカー SDK は、アクセストークンを取得するために正しい OAuth エンドポイントにリダイレクトします。 OneDrive API エンドポイントと OAuth 機関とのマッピングは次のとおりです。

API エンドポイント	OAuth エンドポイント	`endpointHint`
https://graph.microsoft.com/v1.0/	https://login.microsoftonline.com/common/oauth2/v2.0/authorize	N/A
https://api.onedrive.com/v1.0/	https://login.live.com/oauth20_authorize.srf	https://api.onedrive.com
https://contoso-my.sharepoint.com/personal/ryan_contoso_com/	https://login.microsoftonline.com/common/oauth2/authorize	https://contoso-my.sharepoint.com/personal/ryan_contoso_com/

MSA OAuth エンドポイントにリダイレクトします

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "query",
  advanced: {
    endpointHint: "api.onedrive.com",
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }
}

ドキュメントライブラリに直接リダイレクトして、それとは別の場所でアプリが OAuth フローを制御します。

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    endpointHint: "https://contoso.sharepoint.com/shared%20documents/",
    accessToken "INSERT-ACCESS-TOKEN-HERE"
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }

リダイレクト先のページでは、OneDrive SDK スクリプトの読み込みのみが必要になります。

<html>
<script type="text/javascript" src="https://js.live.net/v7.2/OneDrive.js"></script>
</html>

機能をカスタマイズする

ファイルピッカーによりユーザーは Office 365 全体 (OneDrive および SharePoint ドキュメントライブラリを含む) からファイルを選択できるようになりますが、ファイルを開けるソースの場所を制限することが必要になる場合もあります。次に示すプロパティを使用すると、有効にしたもののみに機能を制限できます。

パラメーター名	説明
disable	値が設定されると、ナビゲーションウィンドウが表示されなくなります。
entryLocation	OneDrive ピッカー UI にレンダリングされるドキュメントライブラリを設定します。
sourceTypes	ユーザーがナビゲーションウィンドウで選択できるファイルのソース。

アプリでは、sourceTypes を OneDrive、Recent、Sites のように指定することも、複数のソースを配列 [`OneDrive`, `Recent`] で指定することもできます。また、アプリでは、entryLocation オブジェクトを指定することで、既定の場所の代わりにカスタマイズされたエントリの場所を指定することもできます。カスタマイズされたエントリの場所は、SharePoint ドキュメントライブラリに制限されます。既定のエントリの場所は、ユーザーの OneDrive for Business です。

var odOptions = {
  clientId: "INSERT-APP-ID-HERE",
  action: "download",
  advanced: {
    navigation: {
      entryLocation: {
        sharePoint: {
          sitePath: "THE-SITE-PATH",
          listPath: "THE-LIST-PATH",
          itemPath: "THE-ITEM-PATH"
        }
      },
      sourceTypes: "Sites" /* or an array like ["OneDrive", "Sites"] */
    }
  },
  success: function(files) { /* success handler */ },
  cancel: function() { /* cancel handler */ },
  error: function(error) { /* error handler */ }

OneDrive ファイル ピッカー SDK for JavaScript v7.2 を使用してファイルを開く