オブジェクトメタデータの設定、オブジェクトメタデータのクエリ、PHP V2 向け OSS SDK の使用 - Object Storage Service

このトピックでは、OSS SDK for PHP を使用してオブジェクトメタデータを設定およびクエリする方法について説明します。

使用上の注意

このトピックのサンプルコードでは、中国 (杭州) リージョンのリージョン ID cn-hangzhou を使用しています。デフォルトでは、パブリックエンドポイントを使用してバケット内のリソースにアクセスします。バケットが配置されているのと同じリージョン内の他の Alibaba Cloud サービスを使用してバケット内のリソースにアクセスする場合は、内部エンドポイントを使用します。 OSS のリージョンとエンドポイントの詳細については、「リージョンとエンドポイント」をご参照ください。
オブジェクトメタデータを設定するには、oss:PutObject 権限が必要です。オブジェクトメタデータをクエリするには、oss:GetObject 権限が必要です。詳細については、「RAM ユーザーにカスタムポリシーをアタッチする」をご参照ください。

オブジェクトのアップロード中にオブジェクトメタデータを設定する

次のサンプルコードは、PutObject を使用してオブジェクトをアップロードし、有効期限、アクセス制御リスト (ACL)、および一部のユーザーメタデータなどのオブジェクトメタデータヘッダーを設定します。他のアップロード API 操作を使用する場合も、同様にオブジェクトメタデータを設定できます。

<?php

// 必要な依存関係がロードされるように、autoload ファイルを含めます。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドラインパラメータを定義および記述します。
$optsdesc = [
    "region" => ['help' => 'バケットが配置されているリージョン。', 'required' => True], // (必須) バケットが配置されているリージョンを指定します。
    "endpoint" => ['help' => '他のサービスが OSS にアクセスするために使用できるドメイン名。', 'required' => False], // (オプション) OSS にアクセスするためのエンドポイントを指定します。
    "bucket" => ['help' => 'バケットの名前', 'required' => True], // (必須) バケットの名前を指定します。
    "key" => ['help' => 'オブジェクトの名前', 'required' => True], // (必須) オブジェクトの名前を指定します。
    "file" => ['help' => 'アップロードするファイルのローカルパス。', '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"];       // オブジェクトの名前。
$file = $options["file"];     // ローカルファイルのパス。

// 環境変数からアクセス認証情報を取得します。
// 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);

// ファイルが存在するかどうかを確認します。
if (!file_exists($file)) {
    echo "Error: The specified file does not exist." . PHP_EOL; // ファイルが存在しない場合は、エラーメッセージを出力して終了します。
    exit(1);
}

// ローカルファイルを開き、アップロードの準備をします。
// ローカルファイルを読み取り専用モードで開き、Utils::streamFor を使用してファイルの内容をストリームに変換します。
$body = Oss\Utils::streamFor(fopen($file, 'r'));

// PutObjectRequest オブジェクトを作成して、オブジェクトをアップロードします。
$request = new Oss\Models\PutObjectRequest(
            bucket: $bucket,
            key: $key,
            metadata: [ 'Author' => 'alibaba oss sdk',
                        'Date' => '2024-07-01']); // オブジェクトメタデータを設定します。

$request->body = $body; // リクエスト本文をファイルストリームに設定します。

// アップロード操作を実行します。
$result = $client->putObject($request);

// オブジェクトアップロード操作の結果を表示します。
// HTTP ステータスコード、リクエスト ID、および ETag を表示して、リクエストが成功したかどうかを確認します。
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。たとえば、HTTP ステータスコード 200 は、リクエストが成功したことを示します。
    'request id:' . $result->requestId . PHP_EOL .   // リクエスト ID。リクエストのデバッグまたは追跡に使用されます。
    'etag:' . $result->etag . PHP_EOL               // オブジェクトの ETag。オブジェクトを一意に識別するために使用されます。
);

オブジェクトメタデータをクエリする

HeadObject メソッドを使用してオブジェクトのすべてのメタデータをクエリする

次のサンプルコードは、HeadObject メソッドを使用してオブジェクトのすべてのメタデータをクエリします。

<?php

// 必要な依存関係がロードされるように、autoload ファイルを含めます。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドラインパラメータを定義および記述します。
$optsdesc = [
    "region" => ['help' => 'バケットが配置されているリージョン。', 'required' => True], // (必須) バケットが配置されているリージョンを指定します。
    "endpoint" => ['help' => '他のサービスが OSS にアクセスするために使用できるドメイン名。', 'required' => False], // (オプション) OSS にアクセスするためのエンドポイントを指定します。
    "bucket" => ['help' => 'バケットの名前', 'required' => True], // (必須) バケットの名前を指定します。
    "key" => ['help' => 'オブジェクトの名前', '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 を使用して、環境変数から 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);

// HeadObjectRequest オブジェクトを作成して、オブジェクトのメタデータを取得します。
$request = new Oss\Models\HeadObjectRequest($bucket, $key);

// オブジェクトメタデータをクエリします。
$result = $client->headObject($request);

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

GetObjectMeta メソッドを使用してオブジェクトの部分メタデータをクエリする

説明

GetObjectMeta メソッドを使用して、返されるコンテンツの長さ (ContentLength)、エンティティタグ (ETag)、最終更新日時 (LastModified)、最終アクセス日時 (LastAccessTime)、バージョン ID (VersionId)、および CRC-64 ハッシュ (HashCRC64) を含む、オブジェクトの部分メタデータのみをクエリできます。

次のサンプルコードは、GetObjectMeta メソッドを使用してオブジェクトの部分メタデータをクエリします。

<?php

// 必要な依存関係がロードされるように、autoload ファイルを含めます。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドラインパラメータを定義および記述します。
$optsdesc = [
    "region" => ['help' => 'バケットが配置されているリージョン。', 'required' => True], // (必須) バケットが配置されているリージョンを指定します。
    "endpoint" => ['help' => '他のサービスが OSS にアクセスするために使用できるドメイン名。', 'required' => False], // (オプション) OSS にアクセスするためのエンドポイントを指定します。
    "bucket" => ['help' => 'バケットの名前', 'required' => True], // (必須) バケットの名前を指定します。
    "key" => ['help' => 'オブジェクトの名前', '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 を使用して、環境変数から 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);

// GetObjectMetaRequest オブジェクトを作成して、オブジェクトのメタデータをクエリします。
$request = new Oss\Models\GetObjectMetaRequest($bucket, $key);

// オブジェクトメタデータをクエリします。
$result = $client->getObjectMeta($request);

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

既存のオブジェクトのメタデータを変更する

CopyObject メソッドを使用してオブジェクトメタデータを変更する

次のサンプルコードは、CopyObject メソッドを使用してオブジェクトのメタデータを変更します。

<?php

// 必要な依存関係がロードされるように、autoload ファイルを含めます。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドラインパラメータを定義および記述します。
$optsdesc = [
    "region" => ['help' => 'バケットが配置されているリージョン。', 'required' => True], // (必須) バケットが配置されているリージョンを指定します。
    "endpoint" => ['help' => '他のサービスが OSS にアクセスするために使用できるドメイン名。', 'required' => False], // (オプション) OSS にアクセスするためのエンドポイントを指定します。
    "bucket" => ['help' => 'バケットの名前', 'required' => True], // (必須) コピー先バケットの名前を指定します。
    "key" => ['help' => 'オブジェクトの名前', 'required' => True], // (必須) コピー先オブジェクトの名前を指定します。
    "src-bucket" => ['help' => 'コピー元バケットの名前', 'required' => False], // (オプション) コピー元バケットの名前を指定します。
    "src-key" => ['help' => 'コピー元オブジェクトの名前', '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);

// CopyObjectRequest オブジェクトを作成して、コピー元オブジェクトをコピーします。
$request = new Oss\Models\CopyObjectRequest(
            bucket: $bucket,
            key: $key,
            metadata: [ 'x-oss-meta-tag1' => 'value1',
            'x-oss-meta-tag2' => 'value2'],
            metadataDirective: 'Replace');

if (!empty($options["src-bucket"])) {
    $request->sourceBucket = $options["src-bucket"]; // コピー元バケット名が提供されている場合は、sourceBucket パラメータを指定します。
}
$request->sourceKey = $srcKey; // コピー元オブジェクトの名前を指定します。

// オブジェクトコピー操作を実行します。
$result = $client->copyObject($request);

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

Copier.Copy を使用してオブジェクトメタデータを変更する

Copier.Copy を使用して、コピー元オブジェクトをコピーし、コピー先オブジェクトのメタデータを設定できます。たとえば、既存のすべての元のメタデータを新しいメタデータで上書きしたり、元のメタデータを削除したり、指定されたメタデータヘッダーのみを更新したりできます。コピー操作の完了後にコピー元オブジェクトを削除するかどうかを指定することもできます。

<?php

// 必要な依存関係がロードされるように、autoload ファイルを含めます。
require_once __DIR__ . '/../vendor/autoload.php';

use AlibabaCloud\Oss\V2 as Oss;

// コマンドラインパラメータを定義および記述します。
$optsdesc = [
    "region" => ['help' => 'バケットが配置されているリージョン。', 'required' => True], // (必須) バケットが配置されているリージョンを指定します。
    "endpoint" => ['help' => '他のサービスが OSS にアクセスするために使用できるドメイン名。', 'required' => False], // (オプション) OSS にアクセスするためのエンドポイントを指定します。
    "bucket" => ['help' => 'バケットの名前', 'required' => True], // (必須) バケットの名前を指定します。
    "key" => ['help' => 'オブジェクトの名前', 'required' => True], // (必須) コピー先オブジェクトの名前を指定します。
    "src-key" => ['help' => 'コピー元オブジェクトの名前', '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-metadata-and-tagging-$key"; // コピー先オブジェクトの名前を指定します。
$copyRequest = new Oss\Models\CopyObjectRequest(
    bucket: $bucket,
    key: $dstKey,
    sourceBucket: $bucket,
    sourceKey: $srcKey
);
$copyRequest->metadataDirective = 'REPLACE'; // オブジェクトメタデータを置き換えます。
$copyRequest->metadata = ['test1' => 'val1', 'test2' => 'value2']; // ユーザーメタデータを指定します。
$result = $copier->copy(
    request: $copyRequest,
);
printf(
    'status code:' . $result->statusCode . PHP_EOL . // HTTP ステータスコード。
    'request id:' . $result->requestId . PHP_EOL     // リクエスト ID。
);