ドライブファイルのアップロード、プレビュー、ダウンロード

本ドキュメントでは、ドキュメント / ファイル関連 API を通じてドライブのファイルアップロード、ダウンロード、プレビューなどのフローを実装する方法を説明します。開発者がドライブ関連 API の機能を素早く理解し、利用できるようサポートします。

​

概要

​

学習内容

本チュートリアルでは、操作手順とサンプルを通じて、企業開発者がドライブファイルのアップロード、ダウンロード、プレビューなどの操作を素早く実装できるようにします。

​

学習目標

開発者が自身のアプリを構築できるようになると同時に、DingTalk のベーシック API を利用してドライブファイルのアップロード、プレビュー、ダウンロード機能を組み込めるようになることを目的としています。

​

対象範囲

すべての DingTalk 開発者を対象とします。

​

前提条件

• 開発者権限を取得済み。
• IDE またはその他の開発ツールをインストール済み。
• ドライブの目次内に「テストフォルダー」という名前のフォルダーを作成済み（このフォルダーはテスト用にのみ使用します）。
• node.js をインストールし、環境設定を完了済み。
• maven をインストールし、環境設定を完了済み。
• JDK をインストールし、環境設定を完了済み。

​

開発フロー

1. サイレントログインを通じて、現在のログインメンバーの名前、ロールなどの情報を取得します。ログインについては、Web アプリ（H5 マイクロアプリ）のサイレントログインを参照してください。
2. ドライブファイルのアップロード
   1. ファイル検索 API を呼び出して、ドライブスペース内の「テストフォルダー」を検索し、ファイルの dentryUuid を返します。

​

説明

この API を呼び出す際は、ドライブスペース内に「テストフォルダー」という名前のフォルダーが 1 つだけ存在することを事前に確認してください。そうでない場合、エラーが発生する可能性があります。 2. dentryUuid をもとに ファイルアップロード情報の取得 API を呼び出し、resourceUrls および headers パラメーターを含むファイルのアップロード情報を取得します。 3. OSS の header リクエスト署名方式でファイルをアップロードします。アップロード方法については、ファイルアップロード情報の取得 API のステップ 2 を参照してください。 4. ファイル送信 API を呼び出して、現在のファイルをドライブに送信し、spaceId、parentId、path、uuid などの返却パラメーター値を取得します。 3. ドライブファイルのプレビュー

1. ドライブファイルアップロードの最終送信時に取得した uuid を使用し、URL を結合してファイルを開き、プレビューします。
2. ドライブファイルのダウンロード
   1. スペースリストの取得 API を呼び出してドライブスペース情報を取得し、spaceId を取得します。
   2. spaceId を使って ファイルまたはフォルダーリストの取得 API を呼び出し、ファイルの fileId とファイル名 name を取得します。
   3. 取得した filedId と name を使って ファイルダウンロード情報の取得 API を呼び出し、internalResourceUrls および headers パラメーターを含むファイルのダウンロード情報を取得します。
   4. 上記の内容をもとに、ダウンロード操作を実行します。ダウンロードコードについては、ファイルダウンロード情報の取得 のステップ 2 を参照してください。 説明

​

説明

ファイルパスは現在のプロジェクトのパス + ファイル名となるため、ファイルダウンロード後は自動的にプロジェクトの目次に保存されます。ご自身でご確認ください。

​

ステップ 1: アプリの作成

1. 開発者管理画面 にログインします。
2. アプリ開発 > 社内アプリ > DingTalk アプリ > アプリの作成 をクリックします。
3. アプリ情報を入力します。

   設定項目	必須	設定説明
   アプリ名	はい	アプリ名を入力します。アプリ名の最小文字数は 2 文字です。
   アプリの説明	はい	アプリが提供する製品またはサービスを簡潔に記述します。アプリの説明の最小文字数は 4 文字です。
   アプリアイコン	いいえ	アプリアイコンをアップロードします。アイコンは JPG/PNG 形式、240 px * 240 px 以上、1:1、2 MB 以内、角丸なしのアイコンが必要です。

4. 保存 をクリックし、アプリ詳細ページに進みます。 作成完了後、ベーシック情報 > 認証情報とベーシック情報 をクリックして、アプリの Client ID、Client Secret、AgentId を確認できます。

​

ステップ 2: Web アプリの設定

1. アプリ詳細ページで、アプリ機能 > アプリ機能の追加 をクリックします。
2. Web アプリの追加を選択します。
3. Web アプリ（H5）情報を設定します。

   設定項目	説明
   アプリホーム URL	アプリのホーム URL を入力します。本サンプルでは、後続のテスト用に http://localhost:5173?corpid=$CORPID$ を使用します。本サンプルはローカルテスト専用です。image
   PC 版ホーム URL

4. 設定完了後、保存 をクリックします。

​

ステップ 3: API 権限の追加

正式なテスト時には、以下の権限を追加する必要があります。

• ファイル検索権限：Storage.Dentry.Search
• 企業ストレージファイルアップロード情報読み取り権限：Storage.UploadInfo.Read
• 企業ストレージファイル書き込み権限：Storage.File.Write
• ドライブアプリスペース読み取り権限：Drive.Space.Read
• 企業ストレージファイル読み取り権限：Storage.File.Read
• 企業ストレージファイルダウンロード情報読み取り権限：Storage.DownloadInfo.Read

​

ステップ 4: アプリの公開

1. アプリ設定完了後、アプリを公開する必要があります。アプリ詳細ページで アプリ公開 > バージョン管理と公開 をクリックします。
2. 新しいバージョンの作成 をクリックし、バージョン詳細ページに進みます。
3. バージョン情報を設定します。

   設定項目	説明
   アプリバージョン番号	アプリバージョン番号を入力します。デフォルトバージョンを使用してください。
   バージョンの説明	バージョンの説明情報を入力します。カスタムで構いません。
   公開対象コンテンツ	ワークベンチに表示されるアプリ機能： - Web アプリを選択

   設定完了後、下部の保存をクリックします。
4. 保存成功のポップアップページで、直接公開をクリックします。

   組織管理者でない場合、アプリ公開時には組織管理者の承認が必要です。「自分のみに公開」の場合は管理者の承認は不要です。

​

ステップ 5: サービスの構築

1. 上記ステップを完了し、以下の Demo 実行用のパラメーター情報を取得していることを確認してください。
2. file-demo.zip Demo をダウンロードできます。
3. IDE を開き、ダウンロードした Demo をインポートします。

   サンプルコードは backend（バックエンドコードディレクトリ）と frontend（フロントエンドコードディレクトリ）に分かれています。

4. バックエンドコードディレクトリを開き、resources ディレクトリ内の application.properties ファイルを編集し、clientId（アプリの Client ID） および clientSecret（アプリの Client Secret） パラメーターを入力します。
5. バックエンドサービスをクリックして起動します。 説明
   • バックエンドサービスを起動する前に、Maven および JDK が正しくインストールされ、関連環境が設定されていることを確認してください。IDE を初めてインストールする場合は、IDE 内で関連設定ファイルを編集する必要があります。
   • 5173 番および 8080 番ポートが使用されていないことを確認してください。
6. フロントエンドコードディレクトリを開き、vite.config.ts を編集し、正しい clientId（アプリの Client ID） を入力します。
7. フロントエンドプロジェクトファイルをクリックし、右クリックして ターミナル を選択して開きます。
8. ターミナルウィンドウで、以下のコマンドを実行します。
   1. npm install
   2. npm run dev

      注意：Windows で起動する際は、npm run dev:raw を使用してください。

9. これで、フロントエンドおよびバックエンドサービスが正常に起動しました。

​

ステップ 6: アプリのテスト

1. DingTalk クライアントサイドにログインし、アプリが所属する組織を選択します。
2. ワークベンチ > 追加 をクリックし、先ほど作成した企業アプリを検索して追加操作を完了します。
3. アプリを開き、ローカルファイルを選択 をクリックして、ローカルファイルをドライブにアップロードします。 ファイルを選択後、送信 をクリックします。ファイル情報確認画面で、ユーザーの ID、ファイル名、ファイルサイズを確認できます。
4. アップロード成功後、以下の図のように表示されます。

​

説明

リンクをクリックすると直接ファイルを開けます。または、ファイルを開く ボタンをクリックしてファイルを表示できます。 アップロード成功後、ドライブの「テストフォルダー」内でアップロード済みのファイルを確認できます。

5. ファイルダウンロードボタンをクリックすることで、ファイルのダウンロードが完了します。

​

重要

ファイルダウンロード時に「auth level of org is not enough」エラーメッセージが表示された場合、現在の企業認証レベルが低すぎることを示しています。アップグレード後にご利用ください。詳細は ファイルダウンロード情報の取得 API のエラーコード説明を参照してください。 ファイルダウンロード成功後、プロジェクトの目次内でダウンロード済みのファイルを確認できます。

6. これで、ドライブのアップロード、プレビュー、ダウンロードの全操作が完了しました。