oss php sdk v2 を使用してファイルをアップロードする方法 - Object Storage Service

このトピックでは、Object Storage Service (OSS) SDK for PHP V2 の Uploader モジュールを使用してファイルをアップロードする方法について説明します。

使用方法に関する注意事項

このトピックでは、中国 (杭州) リージョン (cn-hangzhou) のパブリックエンドポイントを例として使用します。同じリージョン内の他の Alibaba Cloud サービスから OSS にアクセスする場合は、内部エンドポイントを使用します。 OSS リージョンとエンドポイントのマッピングの詳細については、「リージョンとエンドポイント」をご参照ください。
ファイルをアップロードするには、oss:PutObject 権限が必要です。詳細については、「RAM ユーザーにカスタムポリシーをアタッチする」をご参照ください。
このトピックでは、環境変数を使用してアクセス資格情報を取得します。アクセス資格情報の設定方法の詳細については、「OSS SDK for PHP のアクセス資格情報を設定する」をご参照ください。

メソッドの定義

アップローダーの概要

OSS SDK for PHP V2 の Uploader モジュールは、ファイルのアップロードを簡素化するための共通 API 操作を提供します。

Uploader モジュールは、マルチパートアップロード操作を使用して、大きなファイルまたはストリームを複数のパートに分割して並列アップロードします。これにより、アップロードのパフォーマンスが向上します。
Uploader モジュールは、再開可能なアップロード機能も提供します。アップロード中に、アップロードされたパートのステータスが記録されます。ネットワークの中断や予期しないプログラムの終了などの問題でアップロードが失敗した場合、記録されたブレークポイントからアップロードを再開できます。

Uploader モジュールには、次の共通メソッドがあります:

final class Uploader
{
	...
    public function __construct($client, array $args = []) // コンストラクタ

    public function uploadFile(Models\PutObjectRequest $request, string $filepath, array $args = []): Models\UploadResult // ファイルをアップロードする

    public function uploadFrom(Models\PutObjectRequest $request, StreamInterface $stream, array $args = []): Models\UploadResult // ストリームをアップロードする
	...
}

リクエストパラメーター

パラメーター	タイプ	説明
request	PutObjectRequest	オブジェクトアップロードのリクエストパラメーター。パラメーターは PutObject 操作のものと同じです。
stream	StreamInterface	アップロードするストリーム。
filePath	string	ローカルファイルのパス。
args	array	(オプション) 構成オプション。

次の表に、args の共通パラメーターを示します。

パラメーター	タイプ	説明
part_size	int	パートサイズ。デフォルト値は 6 MiB です。
parallel_num	int	同時アップロードタスクの数。デフォルト値は 3 です。このパラメーターは、グローバルな同時実行数制限ではなく、単一の呼び出しの同時実行数制限を指定します。
leave_parts_on_error	bool	アップロードが失敗したときにアップロードされたパートを保持するかどうかを指定します。デフォルトでは、アップロードされたパートは保持されません。

newUploader を使用して Uploader インスタンスをインスタンス化するときに、構成オプションを指定してアップロードの動作をカスタマイズできます。また、各アップロード操作に構成オプションを指定して、特定のオブジェクトの動作をカスタマイズすることもできます。

Uploader の構成パラメーターを設定する

$u = $client->newUploader(['part_size' => 10 * 1024 * 1024]); // パートサイズを 10MB に設定

各アップロードリクエストの構成パラメーターを設定する

$u->uploadFile(
    new Oss\Models\PutObjectRequest(
        bucket: 'bucket', // バケット名
        key: 'key' // オブジェクト名
    ),
    filepath: '/local/dir/example', // ローカルファイルのパス
    args: [
        'part_size' => 10 * 1024 * 1024, // パートサイズを 10MB に設定
    ]
);

サンプルコード

次のサンプルコードは、アップローダーを使用してローカルファイルをバケットにアップロードする方法を示しています。

<?php

// 依存ライブラリが正しくロードされるように、オートローダーファイルをインポートします。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドライン引数の説明を定義します。
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // バケットが配置されているリージョン (必須)。
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // エンドポイント (オプション)。
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // バケットの名前 (必須)。
    "key" => ['help' => 'The name of the object', 'required' => True], // オブジェクトの名前 (必須)。
];

// パラメーターの説明を getopt で必要なロングオプション形式に変換します。
// 各パラメーターの後にコロン ":" を追加して、パラメーターに値が必要であることを示します。
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// コマンドライン引数を解析します。
$options = getopt("", $longopts);

// 必須パラメーターが存在することを確認します。
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // パラメーターのヘルプ情報を取得します。
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 必須パラメーターがない場合は、プログラムを終了します。
    }
}

// 解析されたパラメーターから値を抽出します。
$region = $options["region"]; // バケットが配置されているリージョン。
$bucket = $options["bucket"]; // バケットの名前。
$key = $options["key"];       // オブジェクトの名前。

// 環境変数からアクセス資格情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数からアクセスキー ID とアクセスキーシークレットを読み取ります。
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// SDK のデフォルト構成を使用します。
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 資格情報プロバイダーを設定します。
$cfg->setRegion($region); // バケットが配置されているリージョンを設定します。
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // エンドポイントが指定されている場合は、エンドポイントを設定します。
}

// OSS クライアントインスタンスを作成します。
$client = new Oss\Client($cfg);

// アップロードするローカルファイルのパスを定義します。
$filename = "/Users/yourLocalPath/yourFileName"; // ファイルパスの例。

// アップローダーインスタンスを作成します。
$uploader = $client->newUploader();

// マルチパートアップロード操作を実行します。
$result = $uploader->uploadFile(
    request: new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key), // PutObjectRequest オブジェクトを作成し、バケットとオブジェクト名を指定します。
    filepath: $filename, // アップロードするローカルファイルのパスを指定します。
);

// マルチパートアップロードの結果を出力します。
printf(
    'multipart upload status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。 たとえば、200 は成功を示します。
    'multipart upload request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'multipart upload result:' . var_export($result, true) . PHP_EOL  // マルチパートアップロードの詳細な結果。
);

シナリオ

アップローダーを使用してパートサイズと同時実行数を設定する

次のサンプルコードは、パートサイズや同時実行数など、Uploader の構成パラメーターを設定する方法を示しています。

<?php

// 依存ライブラリが正しくロードされるように、オートローダーファイルをインポートします。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドライン引数の説明を定義します。
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // バケットが配置されているリージョン (必須)。
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // エンドポイント (オプション)。
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // バケットの名前 (必須)。
    "key" => ['help' => 'The name of the object', 'required' => True], // オブジェクトの名前 (必須)。
];

// パラメーターの説明を getopt で必要なロングオプション形式に変換します。
// 各パラメーターの後にコロン ":" を追加して、パラメーターに値が必要であることを示します。
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// コマンドライン引数を解析します。
$options = getopt("", $longopts);

// 必須パラメーターが存在することを確認します。
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // パラメーターのヘルプ情報を取得します。
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 必須パラメーターがない場合は、プログラムを終了します。
    }
}

// 解析されたパラメーターから値を抽出します。
$region = $options["region"]; // バケットが配置されているリージョン。
$bucket = $options["bucket"]; // バケットの名前。
$key = $options["key"];       // オブジェクトの名前。

// 環境変数からアクセス資格情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数からアクセスキー ID とアクセスキーシークレットを読み取ります。
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// SDK のデフォルト構成を使用します。
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 資格情報プロバイダーを設定します。
$cfg->setRegion($region); // バケットが配置されているリージョンを設定します。
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // エンドポイントが指定されている場合は、エンドポイントを設定します。
}

// OSS クライアントインスタンスを作成します。
$client = new Oss\Client($cfg);

// マルチパートアップロードに関連するパラメーターを定義します。
$partSize = 100 * 1024; // パートサイズ (バイト単位)。 この例では、パートサイズは 100 KB に設定されています。

// アップロードするローカルファイルのパスを定義します。
$filename = "/Users/yourLocalPath/yourFileName"; // ファイルパスの例。

// アップローダーインスタンスを作成します。
$uploader = $client->newUploader();

// マルチパートアップロード操作を実行します。
$result = $uploader->uploadFile(
    request: new Oss\Models\PutObjectRequest(bucket: $bucket, key: $key), // PutObjectRequest オブジェクトを作成し、バケットとオブジェクト名を指定します。
    filepath: $filename, // アップロードするローカルファイルのパスを指定します。
    args: [ // マルチパートアップロードの動作をカスタマイズするために使用されるオプションのパラメーター。
        'part_size' => $partSize, // カスタムパートサイズ。
        'parallel_num' => 1, // 同時にアップロードするパートの数。
    ]
);

// マルチパートアップロードの結果を出力します。
printf(
    'multipart upload status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。 たとえば、200 は成功を示します。
    'multipart upload request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'multipart upload result:' . var_export($result, true) . PHP_EOL  // マルチパートアップロードの詳細な結果。
);

アップローダーを使用してローカルファイルストリームをアップロードする

次のサンプルコードは、アップローダーを使用してローカルファイルストリームをアップロードする方法を示しています。

<?php

// 依存ライブラリが正しくロードされるように、オートローダーファイルをインポートします。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドライン引数の説明を定義します。
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // バケットが配置されているリージョン (必須)。
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // エンドポイント (オプション)。
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // バケットの名前 (必須)。
    "key" => ['help' => 'The name of the object', 'required' => True], // オブジェクトの名前 (必須)。
];

// パラメーターの説明を getopt で必要なロングオプション形式に変換します。
// 各パラメーターの後にコロン ":" を追加して、パラメーターに値が必要であることを示します。
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// コマンドライン引数を解析します。
$options = getopt("", $longopts);

// 必須パラメーターが存在することを確認します。
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // パラメーターのヘルプ情報を取得します。
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 必須パラメーターがない場合は、プログラムを終了します。
    }
}

// 解析されたパラメーターから値を抽出します。
$region = $options["region"]; // バケットが配置されているリージョン。
$bucket = $options["bucket"]; // バケットの名前。
$key = $options["key"];       // オブジェクトの名前。

// 環境変数からアクセス資格情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数からアクセスキー ID とアクセスキーシークレットを読み取ります。
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// SDK のデフォルト構成を使用します。
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 資格情報プロバイダーを設定します。
$cfg->setRegion($region); // バケットが配置されているリージョンを設定します。
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // エンドポイントが指定されている場合は、エンドポイントを設定します。
}

// OSS クライアントインスタンスを作成します。
$client = new Oss\Client($cfg);

// マルチパートアップロードに関連するパラメーターを定義します。
$partSize = 100 * 1024; // パートサイズ (バイト単位)。 この例では、パートサイズは 100 KB に設定されています。

// アップロードするローカルファイルのパスを定義します。
$filename = "/Users/yourLocalPath/yourFileName"; // ファイルパスの例。

// アップローダーインスタンスを作成します。
$uploader = $client->newUploader();

// マルチパートアップロード操作を実行します。
// LazyOpenStream を使用してファイルをストリームとして開き、ファイル全体が一度にメモリにロードされるのを防ぎます。
$result = $uploader->uploadFrom(
    request: new Oss\Models\PutObjectRequest(
        bucket: $bucket,
        key: $key
    ),
    stream: new \GuzzleHttp\Psr7\LazyOpenStream($filename, 'rb'), // ファイルストリームを読み取り専用モードで開きます。
    args: [
        'part_size' => $partSize, // カスタムパートサイズ。
    ]
);

// アップロード結果を出力します。
printf(
    'upload from status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。 たとえば、200 は成功を示します。
    'upload from request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'upload from result:' . var_export($result, true) . PHP_EOL  // アップロードの詳細な結果。
);

アップローダーを使用してアップロードの進行状況を表示する

次のサンプルコードは、アップローダーを使用してローカルファイルをアップロードするときにアップロードの進行状況を表示する方法を示しています。

<?php

// 依存ライブラリが正しくロードされるように、オートローダーファイルをインポートします。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドライン引数の説明を定義します。
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // バケットが配置されているリージョン (必須)。
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // エンドポイント (オプション)。
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // バケットの名前 (必須)。
    "key" => ['help' => 'The name of the object', 'required' => True], // オブジェクトの名前 (必須)。
];

// パラメーターの説明を getopt で必要なロングオプション形式に変換します。
// 各パラメーターの後にコロン ":" を追加して、パラメーターに値が必要であることを示します。
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// コマンドライン引数を解析します。
$options = getopt("", $longopts);

// 必須パラメーターが存在することを確認します。
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // パラメーターのヘルプ情報を取得します。
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 必須パラメーターがない場合は、プログラムを終了します。
    }
}

// 解析されたパラメーターから値を抽出します。
$region = $options["region"]; // バケットが配置されているリージョン。
$bucket = $options["bucket"]; // バケットの名前。
$key = $options["key"];       // オブジェクトの名前。

// 環境変数からアクセス資格情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数からアクセスキー ID とアクセスキーシークレットを読み取ります。
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// SDK のデフォルト構成を使用します。
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 資格情報プロバイダーを設定します。
$cfg->setRegion($region); // バケットが配置されているリージョンを設定します。
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // エンドポイントが指定されている場合は、エンドポイントを設定します。
}

// OSS クライアントインスタンスを作成します。
$client = new Oss\Client($cfg);

// マルチパートアップロードに関連するパラメーターを定義します。
$partSize = 100 * 1024; // パートサイズ (バイト単位)。 この例では、パートサイズは 100 KB に設定されています。

// アップロードするローカルファイルのパスを定義します。
$filename = "/Users/yourLocalPath/yourFileName"; // ファイルパスの例。

// アップローダーインスタンスを作成します。
$uploader = $client->newUploader();

$request = new \AlibabaCloud\Oss\V2\Models\PutObjectRequest(bucket: $bucket, key: $key);

# アップロードの進行状況を表示するために、アップロード進行状況コールバック関数を設定します。
$request->progressFn = function (int $increment, int $transferred, int $total) {
    echo sprintf("Uploaded: %d" . PHP_EOL, $transferred);
    echo sprintf("This upload: %d" . PHP_EOL, $increment);
    echo sprintf("Total data: %d" . PHP_EOL, $total);
    echo '-------------------------------------------' . PHP_EOL;
};

// マルチパートアップロード操作を実行します。
$result = $uploader->uploadFile(request: $request,filepath: $filename);

// マルチパートアップロードの結果を出力します。
printf(
    'multipart upload status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。 たとえば、200 は成功を示します。
    'multipart upload request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'multipart upload result:' . var_export($result, true) . PHP_EOL  // マルチパートアップロードの詳細な結果。
);

アップローダーを使用してアップロードコールバックを設定する

ファイルのアップロード後にアプリケーションサーバに通知する場合は、次のサンプルコードを使用します。

<?php

// 依存ライブラリが正しくロードされるように、オートローダーファイルをインポートします。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドライン引数の説明を定義します。
$optsdesc = [
    "region" => ['help' => 'The region in which the bucket is located.', 'required' => True], // バケットが配置されているリージョン (必須)。
    "endpoint" => ['help' => 'The domain names that other services can use to access OSS.', 'required' => False], // エンドポイント (オプション)。
    "bucket" => ['help' => 'The name of the bucket', 'required' => True], // バケットの名前 (必須)。
    "key" => ['help' => 'The name of the object', 'required' => True], // オブジェクトの名前 (必須)。
];

// パラメーターの説明を getopt で必要なロングオプション形式に変換します。
// 各パラメーターの後にコロン ":" を追加して、パラメーターに値が必要であることを示します。
$longopts = \array_map(function ($key) {
    return "$key:";
}, array_keys($optsdesc));

// コマンドライン引数を解析します。
$options = getopt("", $longopts);

// 必須パラメーターが存在することを確認します。
foreach ($optsdesc as $key => $value) {
    if ($value['required'] === True && empty($options[$key])) {
        $help = $value['help']; // パラメーターのヘルプ情報を取得します。
        echo "Error: the following arguments are required: --$key, $help" . PHP_EOL;
        exit(1); // 必須パラメーターがない場合は、プログラムを終了します。
    }
}

// 解析されたパラメーターから値を抽出します。
$region = $options["region"]; // バケットが配置されているリージョン。
$bucket = $options["bucket"]; // バケットの名前。
$key = $options["key"];       // オブジェクトの名前。

// 環境変数からアクセス資格情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数からアクセスキー ID とアクセスキーシークレットを読み取ります。
$credentialsProvider = new Oss\Credentials\EnvironmentVariableCredentialsProvider();

// SDK のデフォルト構成を使用します。
$cfg = Oss\Config::loadDefault();
$cfg->setCredentialsProvider($credentialsProvider); // 資格情報プロバイダーを設定します。
$cfg->setRegion($region); // バケットが配置されているリージョンを設定します。
if (isset($options["endpoint"])) {
    $cfg->setEndpoint($options["endpoint"]); // エンドポイントが指定されている場合は、エンドポイントを設定します。
}

// OSS クライアントインスタンスを作成します。
$client = new Oss\Client($cfg);

// マルチパートアップロードに関連するパラメーターを定義します。
$partSize = 100 * 1024; // パートサイズ (バイト単位)。 この例では、パートサイズは 100 KB に設定されています。

// アップロードするローカルファイルのパスを定義します。
$filename = "/Users/yourLocalPath/yourFileName"; // ファイルパスの例。

// アップローダーインスタンスを作成します。
$uploader = $client->newUploader();

// x-oss-callback および x-oss-callback-var ヘッダーを追加します。
// Webhook アドレスを定義します。
 $call_back_url = "http://www.example.com/callback";

// コールバックパラメーター (callback) を構築します: Webhook アドレスとリクエストボディを指定し、Base64 エンコーディングを使用します。
// プレースホルダー {var1} と {var2} を使用して、${x:var1} と ${x:var2} を置き換えます。
$callback_body_template = "bucket={bucket}&object={object}&my_var_1={var1}&my_var_2={var2}";
$callback_body_replaced = str_replace(
    ['{bucket}', '{object}', '{var1}', '{var2}'],
    [$bucket, $key, 'value1', 'value2'],
    $callback_body_template
);
$callback = base64_encode(json_encode([
    "callbackUrl" => $call_back_url,
    "callbackBody" => $callback_body_replaced
]));

// カスタム変数 (callback-var) を構築し、Base64 エンコーディングを使用します。
$callback_var = base64_encode(json_encode([
    "x:var1" => "value1",
    "x:var2" => "value2"
]));

// マルチパートアップロード操作を実行します。
$result = $uploader->uploadFile(
    request: new Oss\Models\PutObjectRequest(
                    bucket: $bucket,
                    key: $key,
                    callback: $callback,
                    callbackVar: $callback_var,), // PutObjectRequest オブジェクトを作成し、バケットとオブジェクト名を指定します。
    filepath: $filename, // アップロードするローカルファイルのパスを指定します。
);

// マルチパートアップロードの結果を出力します。
printf(
    'multipart upload status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。 たとえば、200 は成功を示します。
    'multipart upload request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'multipart upload result:' . var_export($result, true) . PHP_EOL  // マルチパートアップロードの詳細な結果。
);

参照資料

アップローダーの詳細については、「開発者ガイド」をご参照ください。
アップローダーの完全なサンプルコードについては、「GitHub の例」をご参照ください。