メディアファイルをアップロードして業務通知を送信

本ドキュメントでは、ファイルストレージおよびメッセージ通知に関連する API を呼び出して、メディアファイル利用の一連のフローを実現する方法について説明します。まず社内アプリを作成し、ファイルストレージとメッセージ通知が提供する API を利用して、メディアファイルのアップロードおよびメッセージ通知の送信フローを実現します。

​

概要

​

学習内容

本チュートリアルでは、操作手順とサンプルを通じて、企業の開発者がメディアファイルのアップロードを素早く完了し、アップロード成功後に特定のメンバーへ通知を送信できるようサポートします。

​

学習目標

開発者が自身のアプリを構築するスキルを素早く習得し、同時に DingTalk のベーシック API を利用して、添付ファイルのアップロードと業務通知の機能を実現できるようにします。

​

対象範囲

すべての DingTalk 開発者向けです。

​

前提条件

• 開発者権限を取得済みであること。
• IDE またはその他の開発ツールをインストール済みであること。
• node.js をインストールし、関連する環境設定を完了していること。
• maven をインストールし、関連する環境設定を完了していること。
• JDK をインストールし、関連する環境設定を完了していること。

​

開発フロー

1. サイレントログイン方式で現在のログインユーザーの名前、ロールなどの情報を取得します。ログインについては Web アプリ（H5 マイクロアプリ）のサイレントログインを参照してください。
2. メディアファイルをアップロード API を呼び出して特定のファイル（本チュートリアルではローカルファイルを使用しますが、実際の運用では開発者がカスタマイズ可能）をアップロードし、ファイルの media_id（ファイルの一意な識別子）を取得します。
3. メディアファイルの media_id に基づき、サーバー API の 業務通知を送信 API を呼び出して業務通知メッセージを送信します（本ドキュメントでは画像 + action の 2 種類のメッセージ通知を提供しており、コード内で切り替え可能です）。

​

ステップ 1：アプリを作成

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

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

4. 保存 をクリックしてアプリ詳細ページに移動し、ベーシック情報 > 認証情報とベーシック情報 をクリックして、Client ID、Client Secret、AgentId を確認します。

   注意：Client ID、Client Secret、AgentId は後ほど使用するため、必ず保存してください。

​

ステップ 2：Web アプリを設定

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

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

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

​

ステップ 3：API 権限を追加

権限はデフォルトで有効になっているため、申請は不要です。

​

ステップ 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）、filepath（アップロードするファイルの絶対パス）、agentId（アプリの AgentId） などのパラメータを入力します。
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. ワークベンチでアプリにアクセスし、ファイルをアップロード ボタンをクリックしてメディアファイルのアップロードを完了します。

   アップロードするファイルは 50M 未満である必要があります。