Object Body の操作

Kii Cloud では、Object Body に対して次のような機能を提供しています。

  • 中断/再開可能な転送

    指定されたファイルを Object Body としてアップロードしたりダウンロードしたりできます。転送途中での中断と再開をサポートした方式です。

    iOS では、Background Transfer と Kii Cloud SDK 共通の構成による転送の両方をサポートします。Background Transfer を使うと、ファイル転送のプロセスを OS 側に依頼することで効率的にファイルを転送できます。Backgroud Transfer のコードはこちら(アップロード ダウンロード)を、Kii Cloud SDK の構成による転送のコードはこちら(アップロード ダウンロード)をご覧ください。

  • 一括転送

    指定されたファイルを Object Body としてアップロードしたりダウンロードしたりできます。転送途中での中断と再開をサポートしない方式です。

  • Object Body の移動

    ある KiiObject の Object Body を、他の KiiObject に移動できます。

  • Object Body の公開

    Object Body を Web ブラウザーから閲覧できる形で Web 上に公開できます。

  • Object Body の削除

    Object Body だけを削除することができます。キーと値のペアや KiiObject そのものは、そのまま残ります。

各プラットフォームで利用できる機能は以下のとおりです。

プラットフォーム 中断/再開可能な転送 一括転送 Object Body の移動 Object Body の公開 Object Body の削除
Android
iOS ◯※1
JavaScript
Unity
REST ◯※2
Thing ◯※2

※1 Background Transfer による方式もサポートしています。

※2 中断/再開操作に伴うデータの分割制御をユーザープログラムで行う必要があります。

中断/再開可能な転送

ファイルを Object Body としてアップロードしたり、Object Body をファイルにダウンロードしたりできます。中断/再開可能な転送では、ネットワーク切断やユーザー操作などにより転送が中断した場合、この転送を中断箇所から再開することができます。特に、サイズの大きなファイルを不安定なネットワーク環境下で転送する際になどに適しています。

転送の中断や再開は、Kii Cloud SDK が提供する仕組みによって制御します。ここでは、その方式について説明します。

iOS の Backgroud Transfer はここでの方式と異なる実装方式をとります。実装方法は iOS リファレンスガイド を参照してください。

クラス構成

以下にクライアント SDK で Object Body の転送を行うためのクラス構成を示します。

  • KiiObjcet に転送対象のファイルを指定すると、KiiUploader または KiiDownloader を作成できます。これらのオブジェクトにより、アップロード処理とダウンロード処理をコントロールできます。また、転送開始時に、コールバックを指定することで、何バイト中の何バイトまでの転送が完了したかという進捗状況を取得できます。

  • 転送中の KiiUploader と KiiDownloader は、KiiBucket 配下にある KiiRTransferManager で管理されます。ここでは、転送中のファイル一覧が保持されており、転送が完了すると一覧から消去されます。

  • KiiUploader と KiiDownloader は、それぞれ内部に KiiRTransferInfo を持っており、転送中のバイト数などの状況を取得できます。

転送の状態

転送を開始した KiiUploader や KiiDownloader は、インスタンス内に状態を持ちます。状態は KiiRTransferStatus で定義された以下 3 通りの値を持ち、状態遷移図のように遷移します。

シンボル 説明
NOENTRY 転送がない状態です。
ONGOING 転送が実行中の状態です。
SUSPENDED 転送は中断され、再開できる状態です。

NOENTRY 状態に遷移すると、KiiUploader または KiiDownloader インスタンスは KiiRTransferManager の管理下から消えて、ライフサイクルを終えます。

Android では、ONGOING 状態で回復可能なエラーが発生した場合の動きに注意が必要です(iOS にこの動きは該当しません)。たとえば、転送開始時にファイルがなかった場合などは後から回復できるため、KiiUploader または KiiDownloader は SUSPENDED 状態になって残ります。エラーが発生したとき、タスクを取り消したい場合はユーザープログラムで terminate() を実行する必要があります。この処理を忘れると、エラーが発生した KiiUploader や KiiDownloader が KiiRTransferManager の配下に増え続けます。

実装時の注意点

Object Body の取り扱いについては以下の注意点があります。

  • Android では、実行中にプロセスが終了した場合でも転送状況は保持されます。

    • このデータはクライアント SDK 内部でストレージに保存されるため、KiiRTransferManager 配下から削除する実装を行うか、ユーザーが OS の設定画面からモバイルアプリの「データを消去」を実行するまで残ります。
    • 転送中にモバイルアプリのプロセスが終了し、次回にプロセスが起動した場合は SUSPEND 状態で残っています。
    • 転送中にモバイルアプリが切り替わっても、クライアント SDK を使ったプロセスがメモリ上にある場合はそのまま動作を継続します。
  • iOS では、ホームボタンやロックボタンが押されてプロセスが切り替わったとき、クライアント SDK によって自動で転送が中断状態となります。

  • 転送中は対象のファイルに直接アクセスします。SUSPEND 中にローカルのファイル本体が変更された場合などはエラーとなります。

  • プラットフォームによっては複数の転送を同時に実行できるものがあるため、転送結果に矛盾が生じないよう、モバイルアプリ側で管理する必要があります。たとえば、同時に複数のアップロードを行うと、完了した順番によっては意図しない結果になることがあります(ただし、ファイルの内容が混ざったような結果にはなりません)。

  • アップロードが完全に終わるまでは、ダウンロードできるのはそれまでクラウドに登録されていた Object Body の内容です。アップロードが完了すると、新しい Object Body に切り替わります。アップロード完了時にダウンロード中のものがあった場合、そのダウンロードはエラーとなります。

一括転送

一括転送でも、ファイルを対象としたアップロードまたはダウンロードができます。中断/再開可能な転送とは別の API として提供されます。何らかの理由によりアップロードが中断した場合、最初からファイルのアップロードをやり直す必要があります。

転送開始後は、進捗状態の通知や転送の完了をコールバックによって受け取ることができますが、一旦転送を開始するとモバイルアプリ側から転送をキャンセルできません。そのため、安定したネットワーク上で比較的小さなサイズのファイルを転送する場合にのみ使用することをお勧めします。

Object Body の公開

Kii Cloud では、Object Body を Web ブラウザーから直接参照できる形式でインターネット上に公開する機能を用意しています。

Object Body の公開機能を実行すると、kii.com ドメインのサーバーに対する HTTPS の URL が割り当てられます。エンドユーザーがこの URL を利用すると、Web ブラウザーから Object Body のデータをダウンロードしたり参照したりできます。

URL の例を以下に示します。開発者ポータルでアプリケーションの作成先として日本のサーバーを選択した場合、以下のような URL が発行されます({app_id} にはアプリケーションの AppID が入ります)。

https://{app_id}.jp.kiiapps.com/api/x/0123456789abcdef012345678

オブジェクトがユーザースコープやグループスコープにある場合でも、Web ブラウザーから参照する場合は誰でも閲覧できる状態になります。Web ブラウザーから参照する際には、認証も行われません。ただし、ファイルを公開する操作を実行するユーザーは、公開するタイミングで、そのオブジェクトへの読み取り権限を持っている必要があります。

Content-Type

Web ブラウザーからの参照に備え、Object Body に対する Content-Type を設定できます。Content-Type は HTTPS の応答ヘッダに使用されるため、設定によって Web ブラウザーから参照したときの振る舞いを変えることができます。たとえば、image/jpeg であれば画像として表示されますが、application/octet-stream であれば同じデータでもダウンロードする動きになります。

一括転送では、アップロードの時に Content-type を同時に指定します。中断/再開可能な転送の場合は、ファイルの拡張子を元に Content-Type が自動設定されます(拡張子がない場合は application/octet-stream になります)。

有効期限

URL を発行する際には、次の 3 通りの方法で有効期限を指定できます。

  • 有効期限を設定せずに公開
  • 一定時間だけ公開(例:今から 1 時間だけ公開)
  • 指定した日時まで公開(例:3 月 31 日まで公開)

設定した有効期限が過ぎると、URL は無効となりファイルをダウンロードすることができなくなります。Web ブラウザーでアクセスしたときは、HTTP ステータス 410 Gone のエラーとなります。

なお、有効期限内であっても、Object Body が削除されるか、Kii Object が削除された場合は、HTTP ステータス 404 Not Found のエラーとなります。

Object Body と URL の関係

KiiObject に用意されている Object Body 公開用の API を呼び出すと、Kii Cloud は URL を発行して Web ブラウザーからアクセスできる状態になります。公開用の API を複数回呼び出した場合は、1 つの KiiObject に複数の URL が紐付くことになります。このイメージを次に示します。

以下の点にご注意ください。

  • URL は KiiObject に紐付いており、URL にダウンロードされるデータそのものが含まれているわけではありません。新しい Object Body がアップロードされた場合、同じ URL でアクセスしても更新後のデータがダウンロードされます。

  • 有効期限は URL ごとに異なるものを割り当てることもできます。図のように、特定の URL だけ期限切れになることもあります。

  • 一旦公開された URL を、期限切れの前に非公開にすることはできません。非公開にしたい場合は、KiiObject そのものの削除を行います。

  • ObjectBody を公開するには、Object Body のアップロードを完了しておく必要があります。アップロード中やアップロード前の段階で、公開を予約することはできません。

  • ダウンロード時にブラウザーが受け取る Content-Type は、Object Body のアップロード時に指定したもの(またはアップロード時にファイルの拡張子から自動判別されたもの)が使用されます。