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

次のチュートリアルでは、ファイル ピッカー 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 */ }
}

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

既定では、OneDrive ファイル ピッカーは、actionshare に設定されているときに表示専用の共有 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 ユーザーがナビゲーション ウィンドウで選択できるファイルのソース。

アプリでは、sourceTypesOneDriveRecentSites のように指定することも、複数のソースを配列 [`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 */ }