すべてのプロダクト
Search
ドキュメントセンター

:データストレージ

最終更新日:Dec 22, 2023

データストレージ

OSS Android SDK は、’OSSData’ を使用してデータストレージ操作を実行します。ここで、データはアプリケーションの実行時のメモリ内のデータを示します。したがって、アプリケーションの実行時にメモリ内のデータをアップロードする必要がある場合や、OSS からローカルメモリにデータ行を byte[] 配列としてダウンロードして処理する場合は、この種の操作を実行する必要があります。

‘OSSData’ インスタンスを作成するときは、’OSSBucket’ と ‘ObjectKey’ を指定する必要があります。これは、処理する OSS のデータ行を示します。インスタンスは次のように取得されます。

OSSData ossData = ossService.getOssData(OSSBucket ossBucket, String ObjectKey);

1. データのダウンロード

‘OSSData’ インスタンスを作成した後に、指定した ‘OSSBucket’ および ‘ObjectKey’ が OSS に存在するデータに対応している場合、データをダウンロードできます。コードは次のとおりです。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data"); // Constructs an OSSData instance
byte[] data = ossData.get(); // A failed download will throw an exception

ここでは、次の点に注意する必要があります。

  • このコードはあくまでも簡略化されたサンプルです。実際のアプリケーションでは、さまざまな理由によりダウンロードが失敗する可能性があるので、例外をキャッチして処理するコードを作成する必要があります。例外の説明については、以降の章を参照してください。
  • これは同期メソッドであり、メソッドが返されるまでスレッドが停止する場合があります。
  • データの操作を実行するとき、OSS Android SDK はネットワークを介して OSS サーバーとやり取りする必要があります。したがって、このコードは処理に時間がかかる妨害的な操作と考えられます。Android プラットフォームでは、ほとんどのコードはメインスレッド (UI スレッドとも呼ばれます) で実行されます。メインスレッドに時間のかかる妨害的な操作がある場合、コードが正常に実行されない可能性があります。したがって、これらのコードは UI スレッド以外で実行する必要があります。または、SDK によって提供される非同期の ‘getInBackgroud()’ インターフェイスを使用することもできます。詳細については、この章のセクション 2 を参照してください。

さらに、ファイルがフォルダー内にある場合は、’ObjectKey’ にパスを記述する必要があります。

OSSData ossData = ossService.getOssData(sampleBucket, "fileFolder/sample-data"); // Constructs an OSSData instance
byte[] data = ossData.get(); // A failed download will throw an exception

データのダウンロードが完了した後は、’getMeta()’ メソッドを呼び出してメタデータを取得できます。

List<BasicNameValuePair> metaList = OSSData.getMeta();

このメソッドは、データのダウンロードが完了した後でのみ結果を取得できます (非同期ダウンロードの場合、’onSuccess()’ がトリガーされた後)。メタデータを直接取得する場合は、セクション 8 を参照してください。

2. 非同期データダウンロードバージョン

実際、OSS Android SDK には時間がかかるすべてのメソッドに対する非同期バージョンが用意されているため、独自に実装したコールバックメソッドをインポートできます。非同期バージョンは、新しいスレッドで操作を実行し、処理ロジックを非同期にコールバックします。

データのダウンロードの場合は、次のように非同期インターフェイスを使用します。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");
ossData.getInBackground(new GetBytesCallback() {
    @Override
    public void onSuccess(String objectKey, byte[] data) {
        // Here, the downloaded data is processed
    }

    @Override
    public void onProgress(String objectKey, int byteWirtten, int totalSize) {
        // Here, you can perform operations based on the download progress
    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {
        // When a download fails, you can get the exception information and perform exception handling here
    }
});

非同期インターフェイスを使用するときは、必ずコールバックメソッドをインポートしてください。コールバックメソッドが必要ない場合は、空白のままでかまいません。

注意する必要があるのは、これらのコールバックメソッドを実装すると、OSS Android SDK によってタスク処理スレッドで呼び出されるということです。つまり、UI スレッドではないスレッドで実行されます。Android では、UI スレッド以外のスレッドは UI 要素を制御できません。したがって、コールバックメソッドで UI 要素を制御する必要がある場合は、Android によって提供されているメッセージ受け渡しのメカニズムで行う必要があります。この処理に関しては既に多くの参考資料があるので、ここでは説明しません。

最初にコールバックメソッドを UI スレッドに転送して SDK で実行するという方法を使用しないのは、すべてのコールバックメソッドでそのようにすると、SDK の使用シナリオの柔軟性が大きく制限されるためです。

3. データ入力ストリームの取得

データをダウンロードするときは、データ入力ストリームを直接取得して必要な処理を実行することもできます。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data"); // Constructs an OSSData instance
try {
    InputStream inputStream = ossData.getObjectInputStream(); // A failed retrieval will throw an exception
    // do something with inputStream
} catch (OSSException ossException) {

}

4. データのアップロード

アプリケーションを実行するときに、メモリ内のデータを OSS にアップロードする必要がある場合は、最初に ‘OSSBucket’ および ‘ObjectKey’ を指定して ‘OSSData’ インスタンスを作成する必要があります。その後、’setData’ インターフェイスを呼び出して、アップロードするデータとその型を指定します。最後に、アップロードメソッドを呼び出してデータをアップロードします。

アップロードするときは、MD5 のチェックを有効にするかどうかを選択できます。

コードは次のとおりです。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");
ossData.setData(data, "raw"); // Specifies the data to upload and its type
ossData.enableUploadCheckMd5sum(); // Enables the upload MD5 check
ossData.upload(); // Failed uploads will throw an exception

アップロードが完了すると、OSS の ‘sampleBucket’ に対応するバケットに、’sampleData’ という名前の新しいデータ行が作成されます。これにはアップロードした ‘data’ が含まれます。

データのアップロードにも、同じように非同期バージョンがあります。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");
ossData.setData(data, "raw"); // Specifies the data to upload and its type
ossData.enableUploadCheckMd5sum(); // Enables the upload MD5 check
ossData.uploadInBackground(new SaveCallback() {
    @Override
    public void onSuccess(String objectKey) {

    }

    @Override
    public void onProgress(String objectKey, int byteCount, int totalSize) {

    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {

    }
});

アップロードするデータとして、データストリームを設定できます。ただし、その場合は、データストリームから読み取るアップロードデータの長さを指定する必要があります。例:

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");

File fileToUpload = new File("<path/to/file>");
InputStream in = new FileInputStream(fileToUpload);

ossData.setInputstream(in, (int) fileToUpload.length(), "raw");
ossData.enableUploadCheckMd5sum(); // Enables the upload MD5 check

// ossData.upload(); // Failed synchronous uploads will throw an exception

ossData.uploadInBackground(new SaveCallback() {
    @Override
    public void onSuccess(String objectKey) {

    }

    @Override
    public void onProgress(String objectKey, int byteCount, int totalSize) {

    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {

    }
});

5. データの削除

指定した ‘OSSBucket’ および ‘ObjectKey’ に対応するデータを表す ‘OSSData’ インスタンスを作成した後は、削除メソッドを呼び出してそのデータ行を削除できます。コードは次のとおりです。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data"); // Constructs an OSSData instance
ossData.delete(); // Failed deletions will throw an exception

同じように非同期バージョンがあります。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data"); // Constructs an OSSData instance
data.deleteInBackground(new DeleteCallback() {
    @Override
    public void onSuccess(String objectKey) {

    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {

    }
});

削除操作では、進行中の操作は表示されません。実装の進行にコールバックメソッドは必要ありません。次のコピーメソッドも同様です。

6. データのコピー

指定した ‘OSSBucket’ および ‘ObjectKey’ に対する ‘OSSData’ インスタンスが OSS に存在しない場合は作成できます。その後、コピーメソッドを呼び出して、既存の他の OSS データを作成したインスタンスにコピーできます。コピー元としては、同じバケットまたは異なるバケットのデータを使用できます。

コードは次のとおりです。

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");
ossData.copyFrom("sourceData"); // Copies from the same bucket

//または

ossData.copyFrom("sourceBucket", "sourceData"); // Copies from a different bucket

非同期バージョン:

OSSData ossData = ossService.getOssData(sampleBucket, "sample-data");
ossData.copyFromInBackgroud("sourceData", new CopyCallback() {
    @Override
    public void onSuccess(String objectKey) {

    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {

    }
});

//または

ossData.copyFromInBackgroud("sourceBucket", "sourceData", new CopyCallback() {
    @Override
    public void onSuccess(String objectKey) {

    }

    @Override
    public void onFailure(String objectKey, OSSException ossException) {

    }
});

7. ダウンロード時の範囲の指定

データをダウンロードする前に、’Range’ を設定してダウンロードの範囲を指定できます。

ossData.setRange(222, 888)); // This is only valid for a download operation and, to be effective, must be called prior to the download
ossData.setRange(222, Range.INFINITE); // Sets the download range as 222 to the end of the object
OSSData.setRange(Range.INFINITE, 20); // Indicates a download of the last 20 bytes of the object

8. アップロード時のカスタムメタ属性の追加

OSS のデータには独自のメタ属性があります。システムによって自動的に追加されるだけでなく、”x-oss-meta-“ プレフィックスを使用してカスタム属性を指定することもできます。詳細については、OSS プロダクトのドキュメントを参照してください。

アップロード時に指定した属性は、SDK のメタ属性取得メソッドで個別に取得できます。詳細については、ドキュメントの「メタのみの取得」の章を参照してください。

アップロードの前にカスタムメタ属性を追加するためのコードは次のとおりです。

ossData.addXOSSMetaHeader("x-oss-meta-key1", "value1"); // This is only valid for upload operations and, to be effective, must be called prior to the upload
ossData.addXOSSMetaHeader("x-oss-meta-key2", "value2"); // Custom meta attributes must have the "x-oss-meta-" prefix
ossData.addXOSSMetaHeader("x-oss-meta-key3", "value3"); // Meta attribute key-value pairs of the same name are not supported

注意: “x-oss-meta-“ プレフィックスを使用しないでメタ属性を追加した場合は、無視されます。また、メタ属性で中国語を使用して情報を追加することはお勧めしません。使用する場合は、コーデック操作を手動で実行する必要があります。つまり、アップロードする前に手動でエンコードし、ダウンロードした後に手動でデコードする必要があります。

9. データ URL の生成

指定した ‘OSSBucekt’ および ‘objectKey’ のデータを作成した後に、’getResourceURL()’ インターフェイスを呼び出してアクセス URL を生成できます。これを使用して、サードパーティによる URL アクセスを許可できます。データのバケットに ‘公開読み取り’ 権限がない場合は、このインターフェイスの ‘accessKey’ と有効期間をインポートする必要があります。この URL は有効期間が終了した後で期限が切れます。STS 認証モデルを使用している場合、この ‘accessKey’ には任意の値をインポートできます。

OSSData.getResourceURL(String accessKey, int availablePeriodInSeconds); // The generated URL will expire in availablePeriodInSeconds seconds

バケットに ‘公開読み取り’ 権限がある場合は、次のように呼び出すだけです。

OSSData.getResourceURL(); // Because the Bucket has Public-Read permission, you do not need to import an accessKey or validity period

10. 非同期のアップロード/ダウンロードタスクのキャンセル

モバイル端末の場合 (特に、2G/3G ネットワークを使用する端末)、大きなファイルのアップロードおよびダウンロード操作には長い時間がかかることがあります。そのような処理の途中で、なんらかの理由により処理を破棄することが必要になる場合があります。そのような場合のために、OSS Android SDK には、データおよびファイルの非同期アップロード/ダウンロードインターフェイスのためのキャンセル関数があります。非同期タスクを開始した後でインターフェイスが返す ‘TaskHandler’ を使用して ‘cancel()’ インターフェイスを呼び出すことで、そのタスクをキャンセルできます。正常にキャンセルされたタスクは ‘onFailure()’ に入り、’InterruptIOException’ 例外をスローします。

TaskHandler tHandler = OSSData.getInBackground(new GetBytesCallback() {...}); // Starts an asynchronous download task
// doSomething
tHandler.cancel(); // The task must be canceled for some reason