こんにちは、Slack の公式 SDK 開発と日本の Developer Relations を担当している瀬良 (@seratch) と申します 👋
この記事では、本日発表された files.upload API の deprecation (非推奨) と移行方法について日本語で解説します。アナウンスメント（英語）は、以下のページでご確認いただけます。
files.upload API 廃止までの流れ
files.upload API は、2025 年春に廃止されます。それまでのスケジュールは以下の通りです。
- 2024 年 5 月 8 日以降、新しく作成された Slack アプリは files.upload API にアクセスできなくなります。すでに存在している既存のアプリは廃止日（3. 参照）までは API を使用することができます。
- 2024 年 6 月〜 2025 年 2 月の間、files.upload API を利用しているアプリの開発者、そのアプリを管理する Slack ワークスペースの管理者にリマインダーメールを送信します。
- 2025 年 3 月 11 日に files.upload API は廃止されます。以降は呼び出すことができません。
移行方法
移行先のファイルアップロード方法は、Slack のクライアントアプリとほぼ同様な方式になります。詳細については、公式 SDK の紹介の後に解説します。
公式の Node.js、Python、Java SDK を利用している場合は files.upload V2 というメソッドがすでに提供されており、こちらに移行することで同じアプリの機能を維持することができます。
JavaScript/TypeScript (Node.js)
@slack/web-api の WebClient#files.upload() から WebClient#files.uploadV2() (内部の処理は同じなので WebClient#filesUploadV2() でも OK です) に移行します。詳しくは以下を参考にしてください。
Python
slack_sdk.WebClient#files_upload() から WebClient#files_upload_v2() に移行します。詳しくは以下を参考にしてください。
Java/Kotlin
com.slack.api.methods.MethodsClient#filesUpload() から MethodsClient#filesUploadV2() に移行します。詳しくは以下を参考にしてください。
直接 API を利用する場合
上記のランタイム・言語でない場合は、v2 メソッドが内部でやっていることと同じ処理を実装する必要があります。処理は三つのステップに分かれます。
-
files.getUploadURLExternal API を呼び出してファイルアップロードに使用する
https://files.slack.com/upload/v1/...URL とファイル ID を取得する -
https://files.slack.com/upload/v1/...URL に POST リクエストを送信してファイルをアップロードする - files.completeUploadExternal API にファイル ID に加えて チャンネル ID などを送信して、アップロード処理を完了させる
これまでとの違いとしては files.completeUploadExternal API を呼び出して応答が返ってきても、Slack のサーバー側ではまだファイルのセキュリティスキャンなどの処理が続いており、チャンネル内でのファイル共有は非同期で行われるという点です。これは、files.upload API が抱えていた巨大なファイルに対するパフォーマンス問題を解決するためのトレードオフとして挙動が変更されたものです。何卒ご理解いただければと思います。
ファイルのアップロード完了をトリガーに後続の処理を行いたい場合、以下の二つの対応方法があります。
- files.info API を一定間隔でポーリングして、ファイルのメタデータが更新されるまで待つ
- イベント API の file_shared イベント を使って処理を継続する
新しい方式で変更された点
公式 SDK の v2 メソッドを使うと呼び出すメソッドを変えるだけでほぼそのまま動作するはずですが、いくつか挙動の変更点がありますので、まとめておきます。
- 一つのメッセージで複数のファイルを一括アップロードできるようになりました
- ファイルを共有する先を指定するパラメーターが channels -> channel_id に変更され、複数のチャンネルの指定やチャンネル名での指定はできなくなりました
- 上記の通り、アップロード処理の完了は非同期になったので、同期的な後続処理がある場合は files.info API のポーリングまたはイベント API での連携が必要です
終わりに
先日の RTM API の件に続いて、お手数をおかけいたしますが、何卒よろしくお願いいたします 🙇