Object Storage Service:モバイルアプリ向けアップロードコールバックの設定

前提条件

開始する前に、以下の条件を満たしていることを確認してください。

• モバイルアプリ向け直接データ転送の設定 を完了済みであること — Android または iOS アプリが、Security Token Service (STS) トークンを用いて既に OSS へ直接アップロードできる状態であること

• POST リクエストを受信可能なパブリック IP アドレスを持つアプリケーションサーバーがあること

• インターネットからアクセス可能なコールバック URL（例： http://example.com/callback.php）が用意されていること

適用範囲/利用シーン

アプリケーションサーバーがアップロード発生時に即座に対応する必要がある場合に、アップロードコールバックが有効です。

• ユーザー生成コンテンツの追跡：プロフィール写真、ドキュメント、動画などのアップロードユーザー、ファイル名、サイズ、MIME タイプを記録します。

• デバイスメタデータの収集：クライアント側からの別途の API 呼び出しを必要とせず、各アップロードに伴ってアプリバージョン、OS バージョン、GPS 座標、デバイスモデルなどの情報を取得します。

• アップロード後の処理：アップロードが OSS に到着した瞬間に、データベース更新、画像処理、通知送信などの下流ワークフローをトリガーします。

仕組み

このフローには、モバイルアプリ、OSS、アプリケーションサーバーの 3 者が関与します。

1. ステップ 1～4（図示は省略）：モバイルアプリがアプリケーションサーバーと認証を行い、STS トークンを取得します。

2. ステップ 5：Android または iOS アプリが OSS へアップロードリクエストを送信します。このリクエストには、コールバック先の URL を指定する callbackUrl およびコールバックに含めるデータを定義する callbackBody が含まれます。

3. ステップ 6：OSS がオブジェクトを受信した後、callbackUrl に指定されたアプリケーションサーバーへ POST コールバックリクエストを送信します。

4. ステップ 7：アプリケーションサーバーがリクエストを処理し、JSON 形式の応答を返します。OSS はこの応答を、アップロード結果としてモバイルアプリへ転送します。

コールバックの完全な仕様については、「コールバック」をご参照ください。

システム変数

OSS がアプリケーションサーバーへコールバックリクエストを送信する際、callbackBody には、以下のシステム変数の任意の組み合わせを含めることができます。これらの変数を含めるかどうかは、モバイルアプリ側でアップロードリクエストを構成する際に指定します。

モバイルアプリでのアップロードコールバックの構成

コールバックをトリガーするには、すべてのアップロードリクエストに callbackUrl および callbackBody を含める必要があります。また、クライアント側のメタデータをサーバーへ送信するために、x: で始まるカスタム変数を渡すこともできます。

各アップロードリクエストに含めるパラメーター：

カスタム変数の命名規則：カスタム変数は必ず x: で始める必要があります（例： x:phone、x:system、x:gps、x:version）。OSS はこれらの変数を callbackBody 内でそのままアプリケーションサーバーへ転送します。

OSSPutObjectRequest *request = [OSSPutObjectRequest new];
request.bucketName = @"<bucketName>";
request.objectKey  = @"<objectKey>";
request.uploadingFileURL = [NSURL fileURLWithPath:@"<filepath>"];

// コールバック URL およびサーバーへ送信するフィールドを設定します。
request.callbackParam = @{
    @"callbackUrl":  @"http://example.com/callback.php",
    @"callbackBody": @"filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}"
};

// カスタム変数の値を設定します。
request.callbackVar = @{
    @"x:phone":  @"iphone6s",
    @"x:system": @"ios9.1"
};

PutObjectRequest put = new PutObjectRequest(testBucket, testObject, uploadFilePath);

ObjectMetadata metadata = new ObjectMetadata();
metadata.setContentType("application/octet-stream");
put.setMetadata(metadata);

// コールバック URL およびサーバーへ送信するフィールドを設定します。
put.setCallbackParam(new HashMap<String, String>() {{
    put("callbackUrl",  "http://example.com/callback.php");
    put("callbackBody", "filename=${object}&size=${size}&phone=${x:phone}&system=${x:system}");
}});

// カスタム変数の値を設定します。
put.setCallbackVars(new HashMap<String, String>() {{
    put("x:phone",  "iPhone 6s");
    put("x:system", "YunOS5.0");
}});

アプリケーションサーバーの要件

アプリケーションサーバーは、以下の要件を満たす必要があります。

• POST リクエストの受信対応：callbackUrl エンドポイントで POST リクエストを受け付ける必要があります。

• パブリック IP アドレスの保有：OSS からアクセス可能である必要があります。例：http://example.com/callback.php。

• JSON 応答の返却：OSS はこの応答を、アップロード結果としてモバイルアプリへ直接転送します。JSON ボディ内には任意のフィールドを含めることができます。

OSS からのコールバックであることを検証する

アプリケーションサーバーがインターネットに公開されている場合、OSS 以外のソースからもリクエストを受信する可能性があります。コールバックが真正なものであることを確認するには、着信した POST リクエスト内の x-oss-pub-key-url および authorization ヘッダーに対して RSA 署名検証を実行してください。署名検証を通過したリクエストのみが、OSS から送信されたものです。

次のセクションにあるサンプルプログラムには、この RSA 検証ロジックが含まれています。参考としてご活用ください。

アプリケーションサーバーが受信するコールバックリクエストの例（上記の iOS／Android の構成に基づく）：

POST /index.html HTTP/1.0
Host: 203.0.113.0
Connection: close
Content-Length: 81
Content-Type: application/x-www-form-urlencoded
User-Agent: ehttp-client/0.0.1
authorization: kKQe**************/kdD1ktNVgbWE**************
x-oss-pub-key-url: aHR0**************

filename=test.txt&size=5&phone=iphone6s&system=ios9.1

アプリケーションサーバーが署名検証を実行し、リクエストボディを解析した後、抽出されたデータ（ファイル名、サイズ、電話機種、OS バージョンなど）を継続的な管理のために保存できます。

OSS のサーバー応答処理動作

サンプルプログラムのダウンロード

以下のサンプルプログラムは、コールバックサーバー向けの RSA 署名検証を実装しています。各プログラムは着信コールバックの署名検証を実行しますが、callbackBody の解析は行っていません。構成した callbackBody のフィールドに応じて、解析ロジックを追加してください。

• Java

  • ダウンロード：AppCallbackServer.zip

  • 実行：java -jar oss-callback-server-demo.jar 9000（9000 はデフォルトポートであり、必要に応じてポート番号を変更できます）

  • > 注意： この JAR は OSS SDK for Java 1.7 を必要とします。エラーが発生した場合は、同梱の Maven プロジェクトソースを参照し、必要に応じて修正してください。

• PHP

  • ダウンロード：callback-php-demo.zip

  • 実行：Apache 環境へデプロイします。PHP 固有の機能により、特定のヘッダーを取得するには Apache 環境が必要です — 実際の環境に応じてサンプルコードを修正してください。

• Python

  • ダウンロード：callback_app_server.py.zip

  • 実行：python callback_app_server.py — 最小限の HTTP サーバーを起動します。必要に応じて RSA 依存関係をインストールしてください。

• Ruby

  • ダウンロード：oss-callback-server（GitHub）

  • 実行：ruby server.rb

よくある質問