C++용 Azure SDK의 공통 형식

C++용 Azure SDK는 Azure Core 라이브러리의 몇 가지 일반적인 형식을 사용하여 서비스 라이브러리 간에 일관된 기능을 제공합니다. 이러한 유형을 이해하면 Azure 서비스를 보다 효과적으로 사용할 수 있습니다.

핵심 형식

응답<T>

Azure::Response<T> 는 형식화된 응답 값과 원시 HTTP 응답에 대한 액세스를 모두 제공하여 Azure 서비스 작업의 결과를 래핑합니다.

template <class T> class Response final {
public:
  // The value returned by the service
  T Value;
  
  // The HTTP response returned by the service
  std::unique_ptr<Azure::Core::Http::RawResponse> RawResponse;
  
  // Constructor
  explicit Response(T value, std::unique_ptr<Azure::Core::Http::RawResponse> rawResponse)
      : Value(std::move(value)), RawResponse(std::move(rawResponse))
  {
  }
};

사용 예제:

// When calling a service operation that returns a response
auto response = blobClient.GetProperties();

// Accessing the returned value
auto blobProperties = response.Value;

// Accessing the raw HTTP response
auto& rawResponse = *response.RawResponse;
auto statusCode = rawResponse.GetStatusCode();

Nullable<T>

Azure::Nullable<T> 는 존재하거나 존재하지 않을 수 있는 값을 나타냅니다. C++17과 비슷하 std::optional 지만 C++14로 컴파일하는 경우에도 사용할 수 있습니다.

template <class T> class Nullable final {
public:
  // Constructs an empty Nullable
  constexpr Nullable() : m_hasValue(false) {}
  
  // Constructs a Nullable with a value
  constexpr Nullable(T initialValue) : m_value(std::move(initialValue)), m_hasValue(true) {}
  
  // Check if the Nullable contains a value
  bool HasValue() const noexcept { return m_hasValue; }
  
  // Retrieve the value (throws if empty)
  T& Value() & noexcept;
  const T& Value() const& noexcept;
  
  // Get the value or a default
  typename std::remove_cv<T>::type ValueOr(U&& defaultValue) const&;
  
  // Reset to empty state
  void Reset() noexcept;
  
  // Boolean conversion operator
  explicit operator bool() const noexcept { return HasValue(); }
  
  // Dereference operators
  T* operator->() { return std::addressof(m_value); }
  const T* operator->() const { return std::addressof(m_value); }
  T& operator*() & { return m_value; }
  const T& operator*() const& { return m_value; }
};

사용 예제:

// A property that might not have a value
Azure::Nullable<std::string> versionId = blobProperties.VersionId;

// Check if it has a value
if (versionId.HasValue()) {
    // Use versionId.Value() or *versionId
    std::string version = versionId.Value();
    // OR
    std::string version = *versionId;
}

// Using ValueOr to provide a default
std::string version = versionId.ValueOr("default-version");

// Boolean context
if (versionId) {
    // versionId has a value
}

작업<T>

Azure::Core::Operation<T> 는 즉시 완료되지 않을 수 있는 LRO(장기 실행 작업)를 나타냅니다. 작업의 상태를 확인하고 완료를 대기할 수 있습니다.

template <class T> class Operation {
public:
  // Get the current status of the operation
  OperationStatus const& Status() const noexcept;
  
  // Poll for status updates
  Http::RawResponse const& Poll();
  Http::RawResponse const& Poll(Context const& context);
  
  // Wait for the operation to complete
  Response<T> PollUntilDone(std::chrono::milliseconds period);
  Response<T> PollUntilDone(std::chrono::milliseconds period, Context& context);
  
  // Get the result value (only valid when the operation is complete)
  virtual T Value() const = 0;
  
  // Get the raw HTTP response from the last poll
  Http::RawResponse const& GetRawResponse() const;
  
  // Get a token to resume the operation later
  virtual std::string GetResumeToken() const = 0;
};

사용 예제:

// Start a long-running operation
auto operation = sourceBlob.StartCopyFromUri(destinationUri);

// Check the status
if (operation.Status() == Azure::Core::OperationStatus::Succeeded) {
    // Operation already completed
}

// Poll for status updates
operation.Poll();

// Wait for the operation to complete
auto response = operation.PollUntilDone(std::chrono::seconds(1));

// Access the result
auto blobProperties = response.Value;

PagedResponse<T>

Azure::Core::PagedResponse<T> 는 Azure 서비스에서 페이지를 매긴 결과를 처리하기 위한 인터페이스를 제공합니다.

template <class T> class PagedResponse {
public:
  // The current page token
  std::string CurrentPageToken;
  
  // The token for the next page (empty if no more pages)
  Azure::Nullable<std::string> NextPageToken;
  
  // Move to the next page
  void MoveToNextPage(const Context& context = {});
  
  // Check if there are more pages
  bool HasPage() const;
};

사용 예제:

// Get a paged list of containers
auto response = blobServiceClient.ListBlobContainers();

// Process each page
do {
    // Process the current page's results
    for (const auto& container : response.BlobContainers) {
        std::cout << "Container name: " << container.Name << std::endl;
    }
    
    // Continue to next page if available
    if (response.HasPage()) {
        response.MoveToNextPage();
    } else {
        break;
    }
} while (true);

컨텍스트

Azure::Core::Context 는 작업의 수명을 제어하고 취소를 지원합니다.

class Context {
public:
  // Default constructor creates a context with no cancellation
  Context() noexcept;
  
  // Create a context with a timeout
  static Context WithDeadline(Azure::DateTime deadline);
  static Context WithTimeout(std::chrono::milliseconds timeout);
  
  // Create a context with a cancellation signal
  static Context WithCancellation();
  
  // Check if the context has been cancelled
  bool IsCancelled() const noexcept;
  
  // Throw an exception if the context has been cancelled
  void ThrowIfCancelled() const;
  
  // Cancel the context
  static void Cancel(Context& context);
};

사용 예제:

// Create a context with a 30-second timeout
auto context = Azure::Core::Context::WithTimeout(std::chrono::seconds(30));

// Use the context with an operation
auto response = blobClient.DownloadTo(outputStream, {}, context);

// Create a cancelable context
auto cancelableContext = Azure::Core::Context::WithCancellation();

// Cancel the context from another thread
std::thread([&cancelableContext]() {
    std::this_thread::sleep_for(std::chrono::seconds(5));
    Azure::Core::Context::Cancel(cancelableContext);
}).detach();

ETag

Azure::ETag 는 조건부 작업에 사용되는 HTTP 엔터티 태그를 나타냅니다.

class ETag final {
public:
  // Create an ETag from a string
  explicit ETag(std::string etag);
  
  // Get the string representation
  const std::string& ToString() const;
  
  // Comparison operators
  bool operator==(const ETag& other) const;
  bool operator!=(const ETag& other) const;
};

사용 예제:

// Get the ETag from blob properties
Azure::ETag etag = blobProperties.ETag;

// Use the ETag for conditional operations
Azure::Storage::Blobs::DeleteBlobOptions options;
options.IfMatch = etag;
blobClient.Delete(options);

날짜와 시간

Azure::DateTime 는 표준 시간대 정보가 있는 날짜 및 시간 값을 나타냅니다.

class DateTime final {
public:
  // Create a DateTime representing the current time in UTC
  static DateTime Now();
  
  // Parse from string formats
  static DateTime Parse(const std::string& dateTime);
  
  // Format to string
  std::string ToString() const;
};

사용 예제:

// Get the last modified time of a blob
Azure::DateTime lastModified = blobProperties.LastModified;

// Format as a string
std::string formattedTime = lastModified.ToString();

// Use in conditional operations
Azure::Storage::Blobs::GetBlobPropertiesOptions options;
options.IfModifiedSince = lastModified;

Http::RawResponse

Azure::Core::Http::RawResponse 는 서비스의 HTTP 응답을 나타냅니다.

class RawResponse final {
public:
  // Get HTTP status code
  HttpStatusCode GetStatusCode() const;
  
  // Get the reason phrase
  const std::string& GetReasonPhrase() const;
  
  // Get headers
  const CaseInsensitiveMap& GetHeaders() const;
  
  // Get HTTP version
  int32_t GetMajorVersion() const;
  int32_t GetMinorVersion() const;
  
  // Access the body
  std::vector<uint8_t> const& GetBody() const;
  std::unique_ptr<Azure::Core::IO::BodyStream> ExtractBodyStream();
};

사용 예제:

// Access the raw HTTP response
auto& rawResponse = *response.RawResponse;

// Get status code
auto statusCode = rawResponse.GetStatusCode();
if (statusCode == Azure::Core::Http::HttpStatusCode::Ok) {
    // Handle success case
}

// Get headers
auto contentType = rawResponse.GetHeaders().at("content-type");

// Get body as bytes
const auto& bodyBytes = rawResponse.GetBody();

오류 처리

RequestFailedException (요청 실패 예외)

Azure::Core::RequestFailedException 는 서비스 오류의 기본 예외 유형입니다.

class RequestFailedException : public std::runtime_error {
public:
  // Constructor
  RequestFailedException(
      std::string message,
      std::unique_ptr<Azure::Core::Http::RawResponse> rawResponse);
  
  // Get the status code from the response
  Azure::Core::Http::HttpStatusCode StatusCode;
  
  // Get the error code returned by the service
  std::string ErrorCode;
  
  // Get the request ID for troubleshooting
  std::string RequestId;
  
  // Access the raw response that caused this exception
  const Azure::Core::Http::RawResponse& RawResponse() const;
};

사용 예제:

try {
    auto response = blobClient.Delete();
}
catch (const Azure::Core::RequestFailedException& e) {
    std::cerr << "Status code: " << static_cast<int>(e.StatusCode) << std::endl;
    std::cerr << "Error code: " << e.ErrorCode << std::endl;
    std::cerr << "Message: " << e.what() << std::endl;
    std::cerr << "Request ID: " << e.RequestId << std::endl;
}

피드백

이 페이지가 도움이 되었나요?

Last updated on 2025-05-08

다음을 통해 공유

C++용 Azure SDK의 공통 형식

핵심 형식

응답<T>

Nullable<T>

작업<T>

PagedResponse<T>

컨텍스트

ETag

날짜와 시간

Http::RawResponse

오류 처리

RequestFailedException (요청 실패 예외)

피드백

추가 리소스