TransloaditKit
TransloaditKit は、iOS・macOS アプリ向けにファイルのアップロードと処理を提供します。このガイドでは、以下の検証済み構成で TransloaditKit 3.5.0 の
Swift API と TUSKit 3.6.0 を使用します。以前の Objective-C リリースでは API が異なります。リリースの経緯については、当初の発表をご覧ください。
インストール
CocoaPods
pod 'Transloadit', '3.5.0'
pod 'TUSKit', '3.6.0'
この pod の依存関係の範囲は ~> 3.6.0(3.6.0 以上、3.7.0 未満)です。ここで検証したバージョンを使用するには、TUSKit を明示的に固定し、Podfile.lock をプロジェクトとともに保持してください。
Swift Package Manager
Xcode のパッケージ設定で https://github.com/transloadit/TransloaditKit を追加し、バージョンを 3.5.0 に完全一致で指定して、ライブラリプロダクト TransloaditKit を選択してください。このバージョンでは TUSKit が 3.6.0 に固定されています。解決済みの依存関係のバージョンをプロジェクトとともに保持してください。
CocoaPods では Transloadit モジュール、Swift Package Manager では TransloaditKit が公開されます。以下の条件付きインポートは、どちらのインストール方法にも対応しています。
使用方法
Auth Secret は、社内アプリも含め、アプリのバイナリ、Info.plist、アプリがダウンロードする設定に絶対に含めないでください。バックエンドで保持し、アプリが使用する Workspace または Template では
Signature Authentication を必須にしてください。
apiKey:sessionConfiguration:signatureGenerator: イニシャライザーは、Auth Secret を必要とせずに署名を受け取れます。SDK は、署名対象のシリアライズ済み
params 文字列をそのまま提供します。バックエンドでは、ユーザーのセッションを認証し、要求されたアップロードを認可する必要があります。許可するのは、想定した Auth Key、処理設定、送信先、有効期限のみにしてください。余分な Step、任意の Template やフィールド、未知のオプションは拒否してください。ログイン済みの呼び出し元であっても、バックエンドで任意の JSON に署名できてはいけません。クォータとアップロード制限はサーバー側で適用してください。サーバーが管理する Template を使う場合は、allow_steps_override を無効にし、その Template だけを許可してください。
この固定バージョンには、次の 2 つの制約があります。
- Assembly 作成時、
auth.expiresは作成時点から 24 時間後に固定されます。署名コールバックでは、これらのパラメーターを置き換えられません。サーバーポリシーでより短い有効期限が必要な場合は、リクエストを拒否し、バックエンドで Assembly を作成するか、サーバーがパラメーターを制御できる別の Assembly API 連携を使用してください。SDK に合わせてポリシーの有効期限を延長しないでください。 SignatureCompletionパラメーターは nonescaping です。署名ジェネレーターが戻る前に呼び出してください。通常の非同期 HTTP 完了ハンドラーではキャプチャできません。以下のヘルパーは同期的なバックエンド通信処理を受け取り、メインスレッド以外で使用する必要があります。この通信処理には有限のタイムアウトを設定し、失敗時には例外をスローする必要があります。SDK には署名のタイムアウトやフォールバックはありません。
アプリ側で requestSignature を用意します。これは、自身のバックエンドとの認証付き HTTPS 連携処理です。信頼できる固定のエンドポイントに、元の params 文字列を変更せずに送信し、リクエストの Authorization ヘッダーに現在のユーザーセッショントークンを設定します。リダイレクトと成功以外の HTTP レスポンスは拒否してください。このトークンはアプリのログインシステムのものであり、Transloadit のものではありません。バックエンドはリクエストを検証し、承認した元の UTF-8 バイト列に HMAC-SHA384 で署名します。返すのは同じ params 文字列と署名であり、Auth Secret は決して返しません。承認後に再シリアライズしたり、有効期限を変更したりしないでください。セッションが期限切れになった場合は、新しいクライアントを作成する前にセッションを更新してください。
以下の完全なヘルパーは、バックエンドがこの params をそのまま承認し、正しい形式の署名を返したことを確認します。クライアント側の検証は、バックエンドの認可に代わるものではありません。ApprovedSignature はこの例のレスポンス型であり、SDK の型ではありません。
import Foundation
#if canImport(TransloaditKit)
import TransloaditKit
#else
import Transloadit
#endif
struct ApprovedSignature {
let params: String
let signature: String
}
enum SigningError: Error {
case missingSession
case notApproved
}
func makeUploadClient(
authKey: String,
userSessionToken: String,
configuration: URLSessionConfiguration = .default,
requestSignature: @escaping (String, String) throws -> ApprovedSignature
) throws -> Transloadit {
guard !userSessionToken.trimmingCharacters(in: .whitespacesAndNewlines).isEmpty else {
throw SigningError.missingSession
}
return Transloadit(
apiKey: authKey,
sessionConfiguration: configuration,
signatureGenerator: { params, completion in
completion(Result {
let approved = try requestSignature(params, userSessionToken)
let signature = approved.signature
guard approved.params.utf8.elementsEqual(params.utf8),
signature.hasPrefix("sha384:"), signature.count == 103,
signature.dropFirst(7).allSatisfy({ "0123456789abcdef".contains($0) }) else {
throw SigningError.notApproved
}
return signature
})
}
)
}
Assembly の作成
この完全なヘルパーは、リサイズ用の Step を作成し、渡されたローカルファイルをアップロードキューに追加して、処理状況のコールバックを登録します。上記のクライアントヘルパーとともに組み込んでください。この例のバックエンドポリシーでは、fit による
200 × 100 のリサイズを result: true とともに、厳密にこの設定で許可する必要があります。この SDK では、アップロードするファイル数は署名対象の params の外部で送られるため、認可上の制限にはなりません。必要なファイル制限を選択したワークフローで適用できない場合は、許可範囲の広い署名を発行するのではなく、バックエンドから Assembly を作成してください。
func makeResizeStep() -> Step {
Step(
name: "resize",
robot: "/image/resize",
options: [
"width": 200,
"height": 100,
"resize_strategy": "fit",
"result": true
]
)
}
@discardableResult
func uploadImages(
client: Transloadit,
files: [URL],
created: @escaping (Result<Assembly, TransloaditError>) -> Void,
status: @escaping (Result<AssemblyStatus, TransloaditError>) -> Void
) -> TransloaditPoller {
let poller = client.createAssembly(
steps: [makeResizeStep()], andUpload: files, completion: created
)
poller.pollAssemblyStatus(completion: status)
return poller
}
アプリのファイル選択で得た、読み取り可能なローカルファイル URL を
uploadImages に渡し、処理中は Transloadit クライアントを保持してください。署名は同期的に行われるため、バックグラウンドキューで呼び出し、コールバックからの UI 更新はメインキューにディスパッチしてください。両方のコールバックで失敗を処理してください。created コールバックの成功は、Assembly が存在し、アップロードがキューに追加されたことを意味します。アップロードや処理の完了ではありません。ステータスコールバックでは processingStatus を確認してください。completed、aborted、canceled は、それぞれ異なる終了結果です。
ファイルの進捗とアップロードエラーを受け取るには、TransloaditFileDelegate を実装して保持し、クライアントの弱参照プロパティ fileDelegate に設定してください。SDK はポーラーを保持しますが、アプリのライフサイクル、バックグラウンド実行、キャンセル、再開可能なファイルアクセスについては、対象デバイスでの組み込みとテストが別途必要です。これらのヘルパーだけでは、完全なバックグラウンドアップロードアプリケーションにはなりません。
ドキュメント
完全なドキュメントは GitHub をご覧ください。