Object Storage Service:コールバック

制限事項

• 利用可能なリージョン

  コールバックは、China (Hangzhou)、China (Shanghai)、China (Qingdao)、China (Beijing)、China (Zhangjiakou)、China (Hohhot)、China (Ulanqab)、China (Shenzhen)、China (Heyuan)、China (Guangzhou)、China (Chengdu)、China (Hong Kong)、US (Silicon Valley)、US (Virginia)、Japan (Tokyo)、Singapore、Malaysia (Kuala Lumpur)、Indonesia (Jakarta)、Philippines (Manila)、Germany (Frankfurt)、UK (London)、およびUAE (Dubai) で利用できます。

• コールバックの動作

  • コールバックリクエストは、5 秒以内にレスポンスを受け取る必要があります。そうでない場合、リクエストはタイムアウトして失敗します。

  • コールバックの失敗は、ファイルアップロードの完了には影響しません。

  • 失敗したコールバックは自動的に再試行されません。

• 対応 API 操作

  PutObject、PostObject、CompleteMultipartUpload の各 API 操作でコールバックを利用できます。V2 SDK のファイルアップロードマネージャーと署名付き URL でも、コールバックを利用できます。

クライアント側の実装

これらのセクションでは、コールバックパラメーターの構成について説明します。すぐに始めるには、以下の SDK の例を使用してください。

アップロードリクエストに callback パラメーターと、オプションの callback-var パラメーターを含めてください。

1. コールバックパラメーターの構成

   このパラメーターは、アプリケーションサーバーの URL とリクエストボディの形式を定義する、Base64 エンコードされた JSON オブジェクトです。

   1. 基本的な設定例：

      {
      "callbackUrl":"http://oss-demo.aliyuncs.com:23450",
      "callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}"
      }

      この例では：

      • callbackUrl： アプリケーションサーバーの URL。これを実際の URL に変更してください。例： http://oss-demo.aliyuncs.com:23450

      • callbackBody： コールバックリクエストボディのコンテンツ。プレースホルダーとして、バケット名には ${bucket}、オブジェクトのフルパスには ${object}、カスタム変数には ${x:xxx} などを使用します。OSS はコールバック時にプレースホルダーを実際の値に置き換えます。サポートされているプレースホルダーは、「callbackBody のシステムパラメーター」に記載されています。

   2. 高度な設定例：

      {
      "callbackUrl":"http://oss-demo.aliyuncs.com:23450",
      "callbackHost":"oss-cn-hangzhou.aliyuncs.com",
      "callbackBody":"bucket=${bucket}&object=${object}&my_var=${x:my_var}",
      "callbackBodyType":"application/x-www-form-urlencoded",
      "callbackSNI":false
      }

      各フィールドについては、「コールバックパラメーター」で説明しています。

2. オプションの callback-var パラメーターの構成

   重要

   callback-var パラメーターは JSON 形式である必要があります。各カスタムパラメーターのキーは x: で始まり、小文字のみ使用できます (例： x:uid)。

   このパラメーターを使用して、ユーザー ID や注文番号などのカスタム情報をアプリケーションサーバーに渡します：

   {
     "x:uid": "12345",
     "x:order_id": "67890"
   }

   callback-var パラメーターは callbackBody と連携します。callbackBody 内の ${x:xxx} プレースホルダーを使用してカスタム変数を参照します：

   {
     "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
     "callbackBody": "uid=${x:uid}&order=${x:order_id}"
   }

   コールバックがトリガーされると、callbackBodyType が application/x-www-form-urlencoded の場合、OSS は次の内容を送信します：

   uid=12345&order=67890

3. callback および callback-var パラメーターの Base64 エンコード

   • 例： callback パラメーターのエンコード

     元の callback パラメーター：

     {
         "callbackUrl": "http://oss-demo.aliyuncs.com:23450",
         "callbackHost": "your.callback.com",
         "callbackBody": "bucket=${bucket}&object=${object}&uid=${x:uid}&order=${x:order_id}",
         "callbackBodyType": "application/x-www-form-urlencoded",
         "callbackSNI": false
     }

     Base64 エンコードされた結果：

     eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

   • 例： callback-var パラメーターのエンコード

     元の callback-var パラメーター：

     {
       "x:uid": "12345",
       "x:order_id": "67890"
     }

     Base64 エンコードされた結果：

     eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=

4. エンコードされたパラメーターをリクエストに添付

   パラメーターをエンコードした後、次のいずれかの方法で OSS に渡すことができます。

   ヘッダー (推奨)

   SDK またはバックエンドを使用したアップロードに推奨します。コールバックパラメーターは、x-oss-callback および x-oss-callback-var HTTP ヘッダーで渡します：

   • x-oss-callback： Base64 エンコードされた callback パラメーター。

   • x-oss-callback-var (オプション)： Base64 エンコードされた callback-var パラメーター。

   注：リクエスト署名を計算する際には、これら 2 つのヘッダーを正規ヘッダーに含める必要があります。

   例： ヘッダーでコールバックパラメーターを渡す

   PUT /your_object HTTP/1.1
   Host: callback-test.oss-test.aliyun-inc.com
   Accept-Encoding: identity
   Content-Length: 5
   x-oss-callback-var: eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=
   User-Agent: aliyun-sdk-python/0.4.0 (Linux/2.6.32-220.23.2.ali1089.el5.x86_64/x86_64;2.5.4)
   x-oss-callback: eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9
   Host: callback-test.oss-test.aliyun-inc.com
   Expect: 100-Continue
   Date: Wed, 26 Apr 2023 03:46:17 GMT
   Content-Type: text/plain
   Authorization: OSS qn6q**************:77Dv****************
   Test

   POST ボディ

   この方法は、PostObject API を使用するアップロードにのみ適用されます。コールバックパラメーターは、POST リクエストのボディにフォームフィールドとして渡す必要があります。

   • コールバックパラメーター： Base64 エンコードされた JSON 設定を個別のフォームフィールドとして渡します。

     --9431149156168
     Content-Disposition: form-data; name="callback"
     eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9

   • Callback-var パラメーター (カスタム変数)： 各カスタムパラメーターは個別のフォームフィールドとして渡す必要があります。単一の callback-var フィールドにまとめることはできません。

     たとえば、カスタム変数 uid と order_id があるとします。

     {
       "x:uid": "12345",
       "x:order_id": "67890"
     }

     これらを 2 つの個別のフォームフィールドに変換する必要があります。

     --9431149156168
     Content-Disposition: form-data; name="x:uid"
     12345
     --9431149156168
     Content-Disposition: form-data; name="x:order_id"
     67890

   • コールバックパラメーターの検証 (オプション)： ポリシーで条件を指定して、callback パラメーターを検証できます。条件が設定されていない場合、パラメーターはアップロード中に検証されません。例：

     { "expiration": "2021-12-01T12:00:00.000Z",
       "conditions": [
         {"bucket": "examplebucket" },
         {"callback": "eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9"},
         ["starts-with", "$key", "user/eric/"]
       ]
     }

   URL

   • 署名付き URL を使用してファイルをアップロードする場合に使用する方法です。Base64 エンコードされたコールバックパラメーターを URL に追加することで、コールバックをトリガーします。これにより、URL 内にコールバック情報が公開されるため、一時的なアクセスや機密性が低いシナリオでのみ使用してください。

   • URL でコールバックパラメーターを渡す場合は、必須の callback パラメーターと、オプションの callback-var を含めてください。どちらも署名計算のために正規化クエリ文字列の一部である必要があります。署名バージョン 4。

     例：

     PUT /your_object?OSSAccessKeyId=LTAI******************&Signature=vjby*************************************&Expires=1682484377&callback-var=eyJ4OnVpZCI6ICIxMjM0NSIsICJ4Om9yZGVyX2lkIjogIjY3ODkwIn0=&callback=eyJjYWxsYmFja0hvc3QiOiAieW91ci5jYWxsYmFjay5jb20iLCAiY2FsbGJhY2tVcmwiOiAiaHR0cDovL29zcy1kZW1vLmFsaXl1bmNzLmNvbToyMzQ1MCIsICJjYWxsYmFja0JvZHkiOiAiYnVja2V0PSR7YnVja2V0fSZvYmplY3Q9JHtvYmplY3R9JnVpZD0ke3g6dWlkfSZvcmRlcj0ke3g6b3JkZXJfaWR9IiwgImNhbGxiYWNrQm9keVR5cGUiOiAiYXBwbGljYXRpb24veC13d3ctZm9ybS11cmxlbmNvZGVkIiwgImNhbGxiYWNrU05JIjogZmFsc2V9 HTTP/1.1
     Host: callback-test.oss-cn-hangzhou.aliyuncs.com
     Date: Wed, 26 Apr 2023 03:46:17 GMT
     Content-Length: 5
     Content-Type: text/plain

サーバー側の実装

さまざまな言語のコード例については、「サーバー側のコード例」をご参照ください。

アプリケーションサーバーでは、以下を実行する必要があります：

1. OSS からの POST リクエストの受信

   アップロードが成功すると、OSS はコールバック URL に POST リクエストを送信します：

   POST /test HTTP/1.1
   Host: your.callback.com
   Connection: close
   Authorization: GevnM3**********3j7AKluzWnubHSVWI4dY3VsIfUHYWnyw==
   Content-MD5: iKU/O/JB***ZMd8Ftg==
   Content-Type: application/x-www-form-urlencoded
   Date: Tue, 07 May 2024 03:06:13 GMT
   User-Agent: aliyun-oss-callback
   x-oss-bucket: your_bucket
   x-oss-pub-key-url: aHR0cHM6Ly9nb3NzcHVi**********vY2FsbGJeV92MS5wZW0=
   x-oss-request-id: 66399AA50*****3334673EC2
   x-oss-requester: 23313******948342006
   x-oss-signature-version: 1.0
   x-oss-tag: CALLBACK
   bucket=your_bucket&object=your_object&uid=12345&order_id=67890

2. セキュリティのためのリクエスト署名の検証 (オプション)

   リクエストが OSS からのものであることを確認するには、アプリケーションサーバーでその署名を検証してください。「推奨設定」をご参照ください。

   説明

   署名検証はオプションです。

3. コールバックレスポンスの返却

   アプリケーションサーバーは、次の要件を満たすレスポンスを OSS に返す必要があります：

   • アプリケーションサーバーは HTTP/1.1 200 OK を返す必要があります。

   • レスポンスヘッダーには Content-Length を含める必要があります。

   • レスポンスボディは JSON または XML 形式をサポートしています。このトピックの例では JSON を使用します。XML の場合は、レスポンスヘッダーに Content-Type: application/xml を追加してください。

   たとえば、アプリケーションサーバーは {"Status": "OK"} を返すことができます。

   注： この例では Python 2.7.6 を使用しています。新規開発には Python 3 の使用を推奨します。

   HTTP/1.0 200 OK
   Server: BaseHTTP/0.3 Python/2.7.6
   Date: Mon, 14 Sep 2015 12:37:27 GMT
   Content-Type: application/json
   Content-Length: 9
   {"Status": "OK"}

   次に、OSS はこのレスポンスボディをクライアントに転送します。以下にコード例を示します。

   HTTP/1.1 200 OK
   Date: Mon, 14 Sep 2015 12:37:27 GMT
   Content-Type: application/json
   Content-Length: 9
   Connection: keep-alive
   ETag: "D8E8FCA2DC0F896FD7CB4CB0031BA249"
   Server: AliyunOSS
   x-oss-bucket-version: 1442231779
   x-oss-request-id: 55F6BF87207FB30F2640C548
   {"Status": "OK"}

   重要

   CompleteMultipartUpload リクエストの場合、本機能が有効になっていると、元のレスポンスボディにコンテンツ (たとえば、JSON 形式の情報) が含まれていても、アップロードコールバックからのレスポンス (例： {"Status": "OK"}) によって上書きされます。

リクエスト署名の検証

OSS はアップロード後に callbackUrl に POST リクエストを送信します。リクエスト署名を検証して、リクエストが OSS から送信されたことを確認してください。

1. OSS によるコールバックリクエストの署名

   OSS は RSA と MD5 ハッシュを使用してリクエストに署名し、Base64 エンコードされた署名を authorization ヘッダーに設定します。

   • 署名は次のように計算されます：

     authorization = base64_encode(rsa_sign(private_key, url_decode(path) + query_string + '\n' + body, md5))

     説明

     この式では、private_key はプライベートキー、path はコールバックリクエストのリソースパス、query_string はクエリ文字列、body はコールバックボディです。

   • 署名を生成する手順は次のとおりです：

     1. URL デコードしたリソースパス、元のクエリ文字列、改行文字、コールバックボディを連結して、署名対象の文字列を作成します。

     2. RSA で文字列に署名します：キーを使用して文字列に署名します。署名のハッシュ関数は MD5 です。

     3. 署名結果を Base64 エンコードして最終的な署名を取得し、その署名をコールバックリクエストの authorization ヘッダーに設定します。

   • 署名生成の例：

     POST /index.php?id=1&index=2 HTTP/1.0
     Host: 172.16.XX.XX
     Connection: close
     Content-Length: 18
     authorization: kKQeGTRccDKyHB3H9vF+xYMSrmhMZj****/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t****
     Content-Type: application/x-www-form-urlencoded
     User-Agent: http-client/0.0.1
     x-oss-pub-key-url: aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnsr****
     bucket=examplebucket

     path は /index.php、query_string は ?id=1&index=2、body は bucket=examplebucket であり、最終的な署名結果は kKQeGTRccDKyHB3H9vF+xYMSrmhMZj****/kdD1ktNVgbWEfYTQG0G2SU/RaHBovRCE8OkQDjC3uG33esH2t**** です。

2. サーバーによる署名の検証

   リクエスト署名を検証して、真正性を確認してください：

   1. パブリックキーを取得します：

      x-oss-pub-key-url リクエストヘッダーからパブリックキー URL を取得し、Base64 デコードしてください。

      public_key = urlopen(base64_decode(value of x-oss-pub-key-url header))

      デコード前の値の例：

      aHR0cDovL2dvc3NwdWJsaWMuYWxpY2RuLmNvbS9jYWxsYmFja19wdWJfa2V5X3YxLnBlbQ==

      デコード後：

      http://gosspublic.alicdn.com/callback_pub_key_v1.pem

      説明

      パブリックキー URL は http://gosspublic.alicdn.com/ または https://gosspublic.alicdn.com/ で始まる必要があります。ネットワークの問題による影響を回避するため、パブリックキーをローカルにキャッシュしてください。

   2. 署名をデコードします。

      authorization リクエストヘッダーから署名を取得し、Base64 デコードしてください：

      signature = base64_decode(value of authorization header)

   3. 署名対象の文字列を作成します。

      次の形式で、URL デコードしたリソースパス、クエリ文字列、改行文字、コールバックボディを連結してください：

      sign_str = url_decode(path) + query_string + ‘\n’ + body

   4. 署名を検証します。

      RSA パブリックキーと MD5 ハッシュを使用して検証してください：

      result = rsa_verify(public_key, md5(sign_str), signature)

3. 署名検証の例

   次の Python 3 の例は、アプリケーションサーバーで署名を検証する方法を示しています。この例では M2Crypto ライブラリが必要です。

   import http.client
   import base64
   import hashlib
   import urllib.request
   import urllib.parse
   import socket
   from http.server import BaseHTTPRequestHandler, HTTPServer
   from M2Crypto import RSA
   from M2Crypto import BIO
   
   def get_local_ip():
       try:
           csock = socket.socket(socket.AF_INET, socket.SOCK_DGRAM)
           csock.connect(('8.8.8.8', 80))
           (addr, port) = csock.getsockname()
           csock.close()
           return addr
       except socket.error:
           return ""
   
   class MyHTTPRequestHandler(BaseHTTPRequestHandler):
       '''
       def log_message(self, format, *args):
           return
       '''
       def do_POST(self):
           # パブリックキーを取得します。
           pub_key_url = ''
           try:
               pub_key_url_base64 = self.headers['x-oss-pub-key-url']
               pub_key_url = base64.b64decode(pub_key_url_base64).decode()
               if not pub_key_url.startswith("http://gosspublic.alicdn.com/") and not pub_key_url.startswith("https://gosspublic.alicdn.com/"):
                   self.send_response(400)
                   self.end_headers()
                   return
               url_reader = urllib.request.urlopen(pub_key_url)
               # パフォーマンスを向上させるため、パブリックキー URL に基づいてパブリックキーの内容をキャッシュすることを推奨します。
               pub_key = url_reader.read() 
           except Exception as e:
               print('pub_key_url : ' + pub_key_url)
               print('Get pub key failed! Error:', str(e))
               self.send_response(400)
               self.end_headers()
               return
           
           # 署名を取得します。
           authorization_base64 = self.headers['authorization']
           authorization = base64.b64decode(authorization_base64)
           # コールバックボディを取得します。
           content_length = self.headers['content-length']
           callback_body = self.rfile.read(int(content_length))
           # 署名検証用の文字列を作成します。
           auth_str = ''
           pos = self.path.find('?')
           if -1 == pos:
               auth_str = urllib.parse.unquote(self.path) + '\n' + callback_body.decode()
           else:
               auth_str = urllib.parse.unquote(self.path[0:pos]) + self.path[pos:] + '\n' + callback_body.decode()
           print(auth_str)
           # 署名を検証します。
           auth_md5 = hashlib.md5(auth_str.encode()).digest()
           bio = BIO.MemoryBuffer(pub_key)
           rsa_pub = RSA.load_pub_key_bio(bio)
           try:
               result = rsa_pub.verify(auth_md5, authorization, 'md5')
           except:
               result = False
           if not result:
               print('Authorization verify failed!')
               print('Public key : %s' % (pub_key))
               print('Auth string : %s' % (auth_str))
               self.send_response(400)
               self.end_headers()
               return
           
           # コールバックボディに基づいてリクエストを処理します。
           # OSS に応答します。
           resp_body = '{"Status":"OK"}'
           self.send_response(200)
           self.send_header('Content-Type', 'application/json')
           self.send_header('Content-Length', str(len(resp_body)))
           self.end_headers()
           self.wfile.write(resp_body.encode())
   
   class MyHTTPServer(HTTPServer):
       def __init__(self, host, port):
           super().__init__((host, port), MyHTTPRequestHandler)
   
   if __name__ == '__main__':
       server_ip = get_local_ip()
       server_port = 23451
       server = MyHTTPServer(server_ip, server_port)
       server.serve_forever()

   次の表に、他の言語のサーバーサイドコードを示します。

   言語	説明
   Java	ダウンロード URL：Java アプリケーションを実行するには、パッケージを解凍し、コマンド java -jar oss-callback-server-demo.jar 9000 を実行してください (9000 はポート番号で、変更できます)。
   Python	ダウンロード URL：Python パッケージを解凍して python callback_app_server.py を実行してください。このプログラムには RSA 依存関係のインストールが必要です。
   PHP	ダウンロード URL：PHP Apache 環境にデプロイしてください。一部のデータヘッダーは環境によって異なるため、必要に応じてコードを調整してください。
   .NET	ダウンロード URL：.NET 実行方法：パッケージを解凍し、README.md を参照してください。
   Node.js	ダウンロード URL：Node.js 実行するには、パッケージを解凍し、node example.js を実行してください。
   Ruby	ダウンロード URL：Ruby 実行方法： ruby aliyun_oss_callback_server.rb

コールバックパラメーター

次の表では、アップロードが成功した後に OSS が送信するコールバックリクエストを設定するための callback パラメーターについて説明します。

callbackBody のシステムパラメーター

callbackBody フィールドでは、アップロードされたファイル情報をコールバックリクエストで渡すために、次のシステムパラメーターを使用できます。

アップロード失敗時のコールバック

いいえ。コールバックは、アップロードが成功した場合にのみトリガーされます。アップロードが失敗した場合、OSS はコールバックをトリガーせずに、クライアントに直接エラーを返します。

無効な JSON フォーマットのエラー

• アプリケーションサーバーで例外が発生し、有効な JSON フォーマットではないレスポンスボディが返されることがあります。次の図に例を示します。

  解決策：

  • 次のコマンドを実行して内容を確認してください。

    curl -d "<Content>" <CallbackServerURL> -v

  • パケットキャプチャを実行して内容を確認してください。

    Windows では、Wireshark を使用してパケットをキャプチャすることを推奨します。Linux では、tcpdump コマンドを実行してください。

• アプリケーションサーバーが OSS に返すレスポンスボディに、バイトオーダーマーク (BOM) が含まれています。

  このエラーは、PHP アプリケーションでよく発生します。PHP SDK はバイトオーダーマーク (BOM) を返すことがあり、これによりレスポンスボディに 3 バイトが追加され、JSON フォーマットが無効になります。次の図に示すように、3 バイトの ef bb bf が BOM です。

  

  解決策：アプリケーションサーバーのレスポンスボディから BOM を削除してください。