Object Storage Service:OSS SDK for PHP 2.0 を使用してオブジェクトをコピーする

使用上の注意

• このトピックのサンプルコードでは、中国 (杭州) リージョンのリージョン ID cn-hangzhou を使用します。デフォルトでは、パブリックエンドポイントを使用してバケット内のリソースにアクセスします。バケットが配置されているのと同じリージョンにある他の Alibaba Cloud サービスからバケット内のリソースにアクセスする場合は、内部エンドポイントを使用します。OSS がサポートするリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。

• オブジェクトをコピーするには、ソースオブジェクトに対する読み取り権限と、コピー先バケットに対する読み取り/書き込み権限が必要です。

• ソースバケットとコピー先バケットは、同じリージョンに配置する必要があります。たとえば、中国 (杭州) リージョンにあるバケット内のオブジェクトを、中国 (青島) リージョンにあるバケットにコピーすることはできません。

• ソースバケットとコピー先バケットにリテンションポリシーが設定されていないことを確認してください。設定されている場合、「The object you specified is immutable.」というエラーメッセージが返されます。

• このトピックでは、アクセス資格情報は環境変数から取得されます。OSS SDK for PHP 2.0 のアクセス資格情報を設定する方法の詳細については、「PHP のアクセス資格情報を設定する」をご参照ください。

メソッド

Copier

バケットから別のバケットにオブジェクトをコピーしたり、オブジェクトの属性を変更したりする場合は、CopyObject 操作または UploadPartCopy 操作を呼び出すことができます。この 2 つの操作は、それぞれ異なるシナリオに適しています。

• コピー API (CopyObject) は、5 GiB 未満のオブジェクトのコピーにのみ適しています。

• (UploadPartCopy) 操作は、サイズが 5 GiB 以上のオブジェクトのコピーに適しています。この操作は (x-oss-metadata-directive) および (x-oss-tagging-directive) ディレクティブをサポートしていないことに注意してください。マルチパートコピー操作中にメタデータとタグ付けを設定するには、追加の実装が必要です。

OSS SDK for PHP 2.0 で導入された新しいコピーマネージャーである Copier は、オブジェクトをコピーするための高レベルで統一されたインターフェイスを提供します。リクエストパラメーターに基づいて最適なコピー API を自動的に選択し、基盤となる実装の詳細やインターフェイスの違いを抽象化します。Copier の一般的なメソッドは次のように定義されます。

final class Copier
{
    ...
    public function __construct($client, array $args = [])

    public function copy(Models\CopyObjectRequest $request, array $args = []): Models\CopyResult
}

リクエストパラメーター

CopyObjectRequest の共通パラメーター

args の共通パラメーター

Copier クライアントをインスタンス化する際に、構成オプションを指定して、すべてのオブジェクトのデフォルトのダウンロード動作をカスタマイズできます。また、各ダウンロードリクエストで特定のオプションを渡すことで、個々のダウンロードに対してこれらの設定をオーバーライドすることもできます。

• Copier の構成パラメーターを指定します:

  $c = $client->newCopier(['part_size' => 100 * 1024 * 1024]);

• 各コピーリクエストの構成パラメーターを指定します:

  $c->copy(
      new Oss\Models\CopyObjectRequest(
          bucket: 'bucket',
          key: 'key',
          sourceBucket: 'src-bucket',
          sourceKey: 'src-key',
      ),
      args: ['part_size' => 100 * 1024 * 1024]
  );

サンプルコード

次のコードは、ソースバケットからコピー先バケットにオブジェクトをコピーします。デフォルトでは、ソースオブジェクトのメタデータとタグもコピーされます。

<?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], // コピー先オブジェクトの名前。(必須)
    "src-key" => ['help' => 'The name of the source 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"];       // コピー先オブジェクトの名前。
$srcKey = $options["src-key"]; // ソースオブジェクトの名前。

// 環境変数から資格情報情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数から AccessKey ID と AccessKey シークレットを読み取ります。
$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);

// コピー操作を実行するための Copier インスタンスを作成します。
$copier = $client->newCopier();

$dstKey = "multipart-copy-replace-empty-metadata-and-tagging-$key"; // コピー先オブジェクトの名前。
$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: $bucket,
    key: $dstKey,
    sourceBucket: $bucket,
    sourceKey: $srcKey
);
$copyRequest->metadataDirective = 'REPLACE'; // メタデータを置き換えます。
$copyRequest->taggingDirective = 'REPLACE';  // タグを置き換えます。
$result = $copier->copy(request: $copyRequest);

printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。たとえば、200 はリクエストが成功したことを示します。
    'request id:' . $result->requestId . PHP_EOL     // リクエスト ID。リクエストのデバッグや追跡に使用されます。
);

一般的なシナリオ

<?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], // コピー先オブジェクトの名前。(必須)
    "src-key" => ['help' => 'The name of the source 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"];       // コピー先オブジェクトの名前。
$srcKey = $options["src-key"]; // ソースオブジェクトの名前。

// 環境変数から資格情報情報をロードします。
// EnvironmentVariableCredentialsProvider を使用して、環境変数から AccessKey ID と AccessKey シークレットを読み取ります。
$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);

// コピー操作を実行するための Copier インスタンスを作成します。
$copier = $client->newCopier();

// ケース 1: メタデータとタグが空のマルチパートコピー。
$dstKey = "multipart-copy-replace-empty-metadata-and-tagging-$key"; // コピー先オブジェクトの名前。
$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: $bucket,
    key: $dstKey,
    sourceBucket: $bucket,
    sourceKey: $srcKey
);
$copyRequest->metadataDirective = 'REPLACE'; // メタデータを置き換えます。
$copyRequest->taggingDirective = 'REPLACE';  // タグを置き換えます。
$result = $copier->copy(
    request: $copyRequest,
    args: [
        'part_size' => 1 * 1024 * 1024, // パートサイズを 1 MB に指定します。
        'parallel_num' => 5    // コピータスクの同時実行数を 5 に指定します。
    ]
);
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。たとえば、200 はリクエストが成功したことを示します。
    'request id:' . $result->requestId . PHP_EOL     // リクエスト ID。リクエストのデバッグや追跡に使用されます。
);

リファレンス

• コピーマネージャーの完全なサンプルコードについては、「GitHub」をご参照ください。