AWS SDK for PHP 버전 3의 기본 사용 패턴 - AWS SDK for PHP
필수 조건코드에 SDK 포함사용법 요약클라이언트 만들기Sdk클래스 사용서비스 작업 실행비동기 요청결과 객체 작업오류 처리

기계 번역으로 제공되는 번역입니다. 제공된 번역과 원본 영어의 내용이 상충하는 경우에는 영어 버전이 우선합니다.

AWS SDK for PHP 버전 3의 기본 사용 패턴

이 주제에서는 AWS SDK for PHP의 기본 사용 패턴을 중점적으로 살펴봅니다.

필수 조건

코드에 SDK 포함

어떤 기술을 사용하여 SDK를 설치했든 상관없이, 단일 require 문을 사용하여 SDK를 코드에 포함할 수 있습니다. 설치 기법에 가장 적합한 PHP 코드를 찾으려면 다음 표를 참조하세요. /path/to/의 인스턴스를 시스템의 실제 경로로 바꿉니다.

설치 기법 Require 명령문

생성자 사용

require '/path/to/vendor/autoload.php';

phar 사용

require '/path/to/aws.phar';

ZIP 사용

require '/path/to/aws-autoloader.php';

이 항목에서는 Composer 설치 방법을 가정하는 예제를 보여 줍니다. 다른 설치 방법을 사용하는 경우 이 단원으로 돌아와서 사용할 올바른 require 코드를 찾을 수 있습니다.

사용법 요약

SDK를 사용하여 AWS 서비스와 상호 작용하려면 클라이언트 객체를 인스턴스화합니다. 클라이언트 객체에는 서비스 API의 작업과 대응하는 메서드가 있습니다. 특정 작업을 실행하려면 해당 메서드를 호출합니다. 이 메서드는 성공 시 배열과 같은 결과 객체를 반환하고, 실패 시 예외를 발생시킵니다.

클라이언트 만들기

결합형 배열의 옵션을 클라이언트의 생성자에 전달하여 클라이언트를 만들 수 있습니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

샘플 코드 

//Create an S3Client
$s3 = new Aws\S3\S3Client([
    'region' => 'us-east-2'  // Since version 3.277.10 of the SDK,
]);                          // the 'version' parameter defaults to 'latest'.

선택적 “version” 매개변수에 대한 정보는 구성 옵션 항목에서 확인할 수 있습니다.

보안 인증을 클라이언트에 명시적으로 제공하지 않았다는 점에 주의하세요. 왜냐하면 SDK는 환경 변수, HOME 디렉터리의 공유 config 및 credentials 파일, AWS Identity and Access Management (IAM) 인스턴스 프로파일 보안 인증 또는 보안 인증 공급자로부터 보안 인증을 감지하기 때문입니다.

모든 일반 클라이언트 구성 옵션에 대해서는 AWS SDK for PHP 버전 3을 위한 구성에서 자세히 설명합니다. 클라이언트에 제공되는 옵션의 배열은 어떤 클라이언트를 생성하고 있는지에 따라 다를 수 있습니다. 이러한 사용자 지정 클라이언트 구성 옵션에 대해서는 각 클라이언트의 API 설명서에서 설명합니다.

Sdk클래스 사용

Aws\Sdk 클래스는 클라이언트 팩토리 역할을 하며 여러 클라이언트 간의 공유 구성 옵션을 관리하는 데 사용됩니다. 특정 클라이언트 생성자에 제공할 수 있는 동일한 옵션을 Aws\Sdk 클래스에도 제공할 수 있습니다. 그러면 이러한 옵션은 각 클라이언트 생성자에 적용됩니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;

샘플 코드 

// The same options that can be provided to a specific client constructor can also be supplied to the Aws\Sdk class.
// Use the us-west-2 region and latest version of each client.
$sharedConfig = [
    'region' => 'us-west-2'
];
// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);
// Create an Amazon S3 client using the shared configuration data.
$client = $sdk->createS3();

모든 클라이언트 간에 공유되는 옵션은 루트 수준 키-값 페어에 배치됩니다. 서비스(예: "S3", "DynamoDb" 등)의 네임스페이스와 동일한 키에서 서비스별 구성 데이터를 제공할 수 있습니다.

$sdk = new Aws\Sdk([
    'region'   => 'us-west-2',
    'DynamoDb' => [
        'region' => 'eu-central-1'
    ]
]);

// Creating an Amazon DynamoDb client will use the "eu-central-1" AWS Region
$client = $sdk->createDynamoDb();

서비스별 구성 값은 서비스별 값과 루트 수준 값의 결합입니다(즉, 서비스별 값은 루트 수준 값에 얕게 병합됨).

참고

애플리케이션에서 여러 클라이언트 인스턴스를 사용하는 경우 Sdk 클래스를 사용하여 클라이언트를 생성하는 것이 좋습니다. Sdk 클래스는 각 SDK 클라이언트에 동일한 HTTP 클라이언트를 자동으로 사용하여 다른 서비스에 대한 SDK 클라이언트가 비차단 HTTP 요청을 수행할 수 있도록 허용합니다. SDK 클라이언트가 동일한 HTTP 클라이언트를 사용하지 않으면 SDK에서 전송된 HTTP 요청이 서비스 간의 promise 오케스트레이션을 차단할 수 있습니다.

서비스 작업 실행

클라이언트 객체에서 동일한 이름의 메서드를 호출하여 서비스 작업을 실행할 수 있습니다. 예를 들어, Amazon S3 PutObject 운영을 수행하려면 Aws\S3\S3Client::putObject() 메서드를 호출해야 합니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;

샘플 코드 

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2'
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

// Send a PutObject request and get the result object.
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key',
    'Body' => 'this is the body!'
]);

// Download the contents of the object.
$result = $s3Client->getObject([
    'Bucket' => 'my-bucket',
    'Key' => 'my-key'
]);

// Print the body of the result by indexing into the result object.
echo $result['Body'];

클라이언트에 사용할 수 있는 작업과 입력 및 출력의 구조는 서비스 설명 파일을 기반으로 실행 시간에 정의됩니다. 클라이언트를 생성할 때 버전을 제공해야 합니다(예: "2006-03-01" 또는 "최신"). SDK는 제공된 버전을 기반으로 해당 구성 파일을 찾습니다.

putObject()와 같은 작업 메서드는 모두 작업의 파라미터를 나타내는 결합형 배열인 단일 인수를 받습니다. 이 배열의 구조(및 결과 객체의 구조)는 SDK의 API 설명서에서 각 작업에 대해 정의됩니다(예: putObject 작업에 대한 API 설명서 참조).

HTTP 핸들러 옵션

특정 @http 파라미터를 사용하여 기본 HTTP 핸들러가 요청을 실행하는 방법도 미세 조정할 수 있습니다. @http 파라미터에 포함시킬 수 있는 옵션은 "http" 클라이언트 옵션을 사용하여 클라이언트를 인스턴스화할 때 설정할 수 있는 옵션과 동일합니다.

// Send the request through a proxy
$result = $s3Client->putObject([
    'Bucket' => 'my-bucket',
    'Key'    => 'my-key',
    'Body'   => 'this is the body!',
    '@http'  => [
        'proxy' => 'http://192.168.16.1:10'
    ]
]);

비동기 요청

SDK의 비동기 기능을 사용하여 명령을 동시에 전송할 수 있습니다. 작업 이름에 Async라는 접미사를 붙여 요청을 비동기적으로 전송할 수 있습니다. 그러면 요청이 시작되고 promise가 반환됩니다. promise는 성공 시 결과 객체를 통해 이행되거나 실패 시 예외를 통해 거부됩니다. 이러한 방식으로 여러 promise를 생성하여 기본 HTTP 핸들러가 요청을 전송할 때 promise가 HTTP 요청을 동시에 전송하도록 할 수 있습니다.

가져오기 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

샘플 코드 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();
//Listing all S3 Bucket
$CompleteSynchronously = $s3Client->listBucketsAsync();
// Block until the result is ready.
$CompleteSynchronously = $CompleteSynchronously->wait();

promise의 wait 메서드를 사용하여 promise를 동기적으로 강제 완료할 수 있습니다. promise를 강제 완료하면 기본적으로 promise의 상태도 "언래핑" 되므로, promise의 결과를 반환하거나 발생한 예외를 발생시킵니다. promise에서 wait()를 호출하면 HTTP 요청이 완료되고 결과가 채워지거나 예외가 발생할 때까지 프로세스가 차단됩니다.

이벤트 루프 라이브러리와 함께 SDK를 사용할 때는 결과에 대해 차단하지 마세요. 그 대신, 결과의 then() 메서드를 사용하여 작업이 완료될 때 해결되거나 거부되는 promise에 액세스합니다.

가져오기 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

샘플 코드 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);
// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

$promise = $s3Client->listBucketsAsync();
$promise
    ->then(function ($result) {
        echo 'Got a result: ' . var_export($result, true);
    })
    ->otherwise(function ($reason) {
        echo 'Encountered an error: ' . $reason->getMessage();
    });

결과 객체 작업

성공적인 작업을 실행하면 Aws\Result 객체가 반환됩니다. 서비스의 원시 XML 또는 JSON 데이터를 반환하는 대신, SDK는 응답 데이터를 결합형 배열 구조로 강제 변환합니다. SDK는 특정 서비스 및 기본 응답 구조에 대한 지식을 기반으로 데이터의 일부 측면을 정규화합니다.

결합형 PHP 배열과 같이 AWSResult 객체의 데이터에 액세스할 수 있습니다.

가져오기 

require 'vendor/autoload.php';
use Aws\S3\S3Client;
use Aws\Exception\AwsException;

샘플 코드 

// Use the us-east-2 region and latest version of each client.
$sharedConfig = [
    'profile' => 'default',
    'region' => 'us-east-2',
];

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk($sharedConfig);

// Use an Aws\Sdk class to create the S3Client object.
$s3 = $sdk->createS3();
$result = $s3->listBuckets();
foreach ($result['Buckets'] as $bucket) {
    echo $bucket['Name'] . "\n";
}

// Convert the result object to a PHP array
$array = $result->toArray();

결과 객체의 콘텐츠는 실행되는 작업과 서비스의 버전에 따라 다릅니다. 각 API의 결과 구조는 각 작업에 대한 API 설명서에서 문서화됩니다.

SDK는 JSON 데이터 또는 우리의 경우 PHP 배열을 검색하고 조작하는 데 사용되는 DSL인 JMesPath와 통합됩니다. 결과 객체에는 결과에서 데이터를 더 선언적으로 추출하기 위해 사용할 수 있는 search() 메서드가 포함됩니다.

샘플 코드 

$s3 = $sdk->createS3();
$result = $s3->listBuckets();

$names = $result->search('Buckets[].Name');

오류 처리

동기 오류 처리

작업을 수행하는 동안 오류가 발생할 경우 예외가 발생합니다. 이러한 이유로 코드에서 오류를 처리해야 하는 경우 작업 둘레에 try/catch 블록을 사용해야 합니다. 오류가 발생하면 SDK는 서비스별 예외를 발생시킵니다.

다음 예제에서는 Aws\S3\S3Client를 사용합니다. 오류가 있는 경우 발생한 예외는 Aws\S3\Exception\S3Exception 유형입니다. SDK가 발생시키는 모든 서비스별 예외는 Aws\Exception\AwsException 클래스에서 확장됩니다. 이 클래스에는 request-id, 오류 코드 및 오류 유형을 포함하여 실패에 대한 유용한 정보가 포함되어 있습니다. 이를 지원하는 몇 가지 서비스를 참고하고, 응답 데이터는 결합형 배열 구조(Aws\Result 객체와 유사함)로 강제 변환되며, 이는 일반 PHP 결합형 배열처럼 액세스할 수 있습니다. toArray() 메서드는 존재할 경우 어떤 데이터이든 반환합니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;
use Aws\S3\Exception\S3Exception;

샘플 코드 

// Create an SDK class used to share configuration across clients.
$sdk = new Aws\Sdk([
    'region'   => 'us-west-2'
]);

// Use an Aws\Sdk class to create the S3Client object.
$s3Client = $sdk->createS3();

try {
    $s3Client->createBucket(['Bucket' => 'my-bucket']);
} catch (S3Exception $e) {
    // Catch an S3 specific exception.
    echo $e->getMessage();
} catch (AwsException $e) {
    // This catches the more generic AwsException. You can grab information
    // from the exception using methods of the exception object.
    echo $e->getAwsRequestId() . "\n";
    echo $e->getAwsErrorType() . "\n";
    echo $e->getAwsErrorCode() . "\n";

    // This dumps any modeled response data, if supported by the service
    // Specific members can be accessed directly (e.g. $e['MemberName'])
    var_dump($e->toArray());
}

비동기 오류 처리

비동기 요청을 전송할 때는 예외가 발생하지 않습니다. 그 대신, 반환된 promise의 then() 또는 otherwise() 메서드를 사용하여 결과 또는 오류를 수신해야 합니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;
use Aws\S3\Exception\S3Exception;

샘플 코드 

//Asynchronous Error Handling
$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);
$promise->otherwise(function ($reason) {
    var_dump($reason);
});

// This does the same thing as the "otherwise" function.
$promise->then(null, function ($reason) {
    var_dump($reason);
});

그 대신 promise를 "언래핑"하고 예외를 발생시킬 수 있습니다.

가져오기 

require 'vendor/autoload.php';

use Aws\S3\S3Client;
use Aws\Exception\AwsException;
use Aws\S3\Exception\S3Exception;

샘플 코드 

$promise = $s3Client->createBucketAsync(['Bucket' => 'my-bucket']);

//throw exception
try {
    $result = $promise->wait();
} catch (S3Exception $e) {
    echo $e->getMessage();
}