Cloud Storage 객체 재작성

Cloud Storage에서 객체를 재작성하면 위치 간 이동, 암호화 키 순환, 스토리지 클래스 변경과 같이 기존 객체가 복사되거나 변환됩니다. 객체 크기 및 재작성 매개변수에 따라 Cloud Storage는 단일 호출로 작업을 완료하거나 rewrite_token로 중간 진행 상황을 반환할 수 있습니다. 호출이 rewrite_token를 반환하면 재작성이 완료될 때까지 해당 토큰을 후속 요청에 전달합니다.

이 문서에서는 Rust용 Cloud 클라이언트 라이브러리에서 rewrite_until_done 도우미 또는 수동 루프를 사용하여 재작성 요청을 구성하고 재작성 루프를 구동하는 방법을 보여줍니다. 클라이언트 라이브러리를 처음 사용하는 경우 먼저 Rust에서 Cloud Storage 사용을 참조하세요.

시작하기 전에

이 문서의 코드를 실행하기 전에 다음 기본 요건을 완료하세요.

• 결제가 사용 설정된 Google Cloud 프로젝트를 만들거나 선택합니다.
• 프로젝트에 전용 테스트 Cloud Storage 버킷을 만듭니다.
• 환경에 애플리케이션 기본 사용자 인증 정보를 구성합니다.
• 주 구성원에게 버킷의 객체를 읽고, 쓰고, 삭제할 수 있는 권한이 있는 Identity and Access Management(IAM) 역할(예: 스토리지 관리자(roles/storage.admin))을 부여합니다.

종속 항목

Cloud Storage 클라이언트 라이브러리 및 지원 크레이트를 Cargo.toml 파일에 추가합니다.

cargo add google-cloud-storage google-cloud-gax anyhow bytes
cargo add tokio --features macros,rt-multi-thread

클라이언트 및 재작성 요청 준비

자동 도우미와 수동 루프는 모두 구성된 StorageControl 클라이언트 및 RewriteObject 요청 빌더에서 시작됩니다. projects/_/buckets/BUCKET_ID 형식으로 bucket_name를 허용하는 범위 내에서 다음 단계를 완료합니다.

1. 재시도 정책을 사용하여 StorageControl 클라이언트를 초기화합니다. 요청당 최소 30초를 허용하는 것이 좋습니다. 이 예시에서는 5회 시도 제한이 있고 작업별 전체 시간 제한이 없는 RetryableErrors를 사용합니다.

   let control = StorageControl::builder()
       .with_retry_policy(RetryableErrors.with_attempt_limit(5))
       .build()
       .await?;

2. rewrite_object 요청 빌더를 만들고, 클라이언트가 일시적인 오류를 재시도할 수 있도록 요청을 멱등으로 표시하고, 소스 및 대상 버킷과 객체 이름을 설정합니다.

   let mut builder = control
       .rewrite_object()
       .with_idempotency(true) // retry transient errors
       .set_source_bucket(bucket_name)
       .set_source_object(&source_object.name)
       .set_destination_bucket(bucket_name)
       .set_destination_name("rewrite-object-clone");

3. 선택사항: 개별 요청이 더 긴 요청 제한 시간을 요구하는 대신 진행 상황을 더 빠르게 반환하도록 호출당 다시 작성되는 최대 바이트 수를 제한합니다. 이 예시에서는 작은 1MiB 한도를 설정하여 여러 반복을 강제합니다. 프로덕션에서는 더 큰 값을 사용합니다.

   builder = builder.set_max_bytes_rewritten_per_call(1024 * 1024);

4. 선택 사항: 대상 객체 메타데이터를 지정합니다. 예를 들어 저장 클래스를 Nearline(NEARLINE)으로 변경합니다.

   builder = builder.set_destination(Object::new().set_storage_class("NEARLINE"));

   참고: Nearline, Coldline, Archive 스토리지 클래스는 최소 저장 기간을 적용합니다. 이 기간이 끝나기 전에 객체를 삭제하거나 덮어쓰면 조기 삭제 요금이 부과될 수 있습니다.

재작성 루프 자동 실행

대부분의 사용 사례에서는 RewriteObjectExt 특성을 범위로 가져와 요청 빌더에서 rewrite_until_done를 호출합니다. 이 도우미는 반복 전체에서 rewrite_token를 관리하고 재작성이 완료된 후 대상 Object 메타데이터로 확인됩니다.

use google_cloud_storage::builder_ext::RewriteObjectExt;
let dest_object = builder.rewrite_until_done().await?;
println!("dest_object={dest_object:?}");

수동으로 재작성 루프 실행

중간 바이트 수, 체크포인트 진행 상황을 로깅하거나 다른 프로세스에서 다시 쓰기를 재개해야 하는 경우 다시 쓰기 루프를 수동으로 구동합니다.

1. 단일 RewriteObject 요청을 전송하고 진행 상황을 로깅하며 resp.done가 true일 때 완료된 Object 메타데이터 또는 다음 rewrite_token를 반환하는 도우미 함수를 정의합니다.

   enum RewriteProgress {
       // This holds the rewrite token
       Incomplete(String),
       Done(Box<Object>),
   }
   
   async fn make_one_request(builder: RewriteObject) -> Result<RewriteProgress> {
       let resp = builder.send().await?;
       if resp.done {
           println!(
               "DONE:     total_bytes_rewritten={}; object_size={}",
               resp.total_bytes_rewritten, resp.object_size
           );
           return Ok(RewriteProgress::Done(Box::new(
               resp.resource
                   .expect("A `done` response must have an object."),
           )));
       }
       println!(
           "PROGRESS: total_bytes_rewritten={}; object_size={}",
           resp.total_bytes_rewritten, resp.object_size
       );
       Ok(RewriteProgress::Incomplete(resp.rewrite_token))
   }

2. 루프에서 도우미를 호출하여 각 반복에서 요청 빌더를 클론하고 make_one_request가 RewriteProgress::Incomplete를 반환할 때마다 반환된 토큰을 set_rewrite_token에 전달합니다.

   let dest_object = loop {
       let progress = make_one_request(builder.clone()).await?;
       match progress {
           RewriteProgress::Incomplete(rewrite_token) => {
               builder = builder.set_rewrite_token(rewrite_token);
           }
           RewriteProgress::Done(object) => break object,
       };
   };
   println!("dest_object={dest_object:?}");

참고: 재작성 토큰은 최대 1주일 동안 유효하므로 rewrite_token를 저장하고 일치하는 요청 매개변수를 사용하여 다른 프로세스에서 중단된 재작성을 재개할 수 있습니다.

코드 완성

다음 예시에서는 3MiB 소스 객체를 업로드하고 수동 루프를 사용하여 1MiB 단위로 Nearline Storage 클래스에 다시 작성합니다. 재작성이 완료되면 예시에서 테스트 객체와 빈 테스트 버킷을 삭제합니다.

use gcs::Result;
use gcs::builder::storage_control::RewriteObject;
use gcs::client::StorageControl;
use gcs::model::Object;
use gcs::retry_policy::RetryableErrors;
use google_cloud_gax::options::RequestOptionsBuilder;
use google_cloud_gax::retry_policy::RetryPolicyExt as _;
use google_cloud_storage as gcs;

pub async fn rewrite_object(bucket_name: &str) -> anyhow::Result<()> {
    let source_object = upload(bucket_name).await?;

    let control = StorageControl::builder()
        .with_retry_policy(RetryableErrors.with_attempt_limit(5))
        .build()
        .await?;

    let mut builder = control
        .rewrite_object()
        .with_idempotency(true) // retry transient errors
        .set_source_bucket(bucket_name)
        .set_source_object(&source_object.name)
        .set_destination_bucket(bucket_name)
        .set_destination_name("rewrite-object-clone");

    // Optionally limit the max bytes written per request.
    builder = builder.set_max_bytes_rewritten_per_call(1024 * 1024);

    // Optionally change the storage class to force GCS to copy bytes
    builder = builder.set_destination(Object::new().set_storage_class("NEARLINE"));

    let dest_object = loop {
        let progress = make_one_request(builder.clone()).await?;
        match progress {
            RewriteProgress::Incomplete(rewrite_token) => {
                builder = builder.set_rewrite_token(rewrite_token);
            }
            RewriteProgress::Done(object) => break object,
        };
    };
    println!("dest_object={dest_object:?}");

    cleanup(control, bucket_name, &source_object.name, &dest_object.name).await;
    Ok(())
}

enum RewriteProgress {
    // This holds the rewrite token
    Incomplete(String),
    Done(Box<Object>),
}

async fn make_one_request(builder: RewriteObject) -> Result<RewriteProgress> {
    let resp = builder.send().await?;
    if resp.done {
        println!(
            "DONE:     total_bytes_rewritten={}; object_size={}",
            resp.total_bytes_rewritten, resp.object_size
        );
        return Ok(RewriteProgress::Done(Box::new(
            resp.resource
                .expect("A `done` response must have an object."),
        )));
    }
    println!(
        "PROGRESS: total_bytes_rewritten={}; object_size={}",
        resp.total_bytes_rewritten, resp.object_size
    );
    Ok(RewriteProgress::Incomplete(resp.rewrite_token))
}

// Upload an object to rewrite
async fn upload(bucket_name: &str) -> anyhow::Result<Object> {
    let storage = gcs::client::Storage::builder().build().await?;
    // We need the size to exceed 1MiB to exercise the rewrite token logic.
    let payload = bytes::Bytes::from(vec![65_u8; 3 * 1024 * 1024]);
    let object = storage
        .write_object(bucket_name, "rewrite-object-source", payload)
        .send_unbuffered()
        .await?;
    Ok(object)
}

// Clean up the resources created in this sample
async fn cleanup(control: StorageControl, bucket_name: &str, o1: &str, o2: &str) {
    let _ = control
        .delete_object()
        .set_bucket(bucket_name)
        .set_object(o1)
        .send()
        .await;
    let _ = control
        .delete_object()
        .set_bucket(bucket_name)
        .set_object(o2)
        .send()
        .await;
    let _ = control.delete_bucket().set_name(bucket_name).send().await;
}

출력은 다음과 비슷하며, 세 번의 반복에 걸친 진행 상황과 대상 객체 메타데이터를 보여줍니다.

PROGRESS: total_bytes_rewritten=1048576; object_size=3145728
PROGRESS: total_bytes_rewritten=2097152; object_size=3145728
DONE:     total_bytes_rewritten=3145728; object_size=3145728
dest_object=Object { name: "rewrite-object-clone", ... }

삭제

샘플이 조기에 종료되거나 정리 도우미 없이 개별 스니펫을 실행하는 경우 남아 있는 테스트 객체를 삭제하고 완료되면 테스트 버킷을 삭제하여 Google Cloud 계정에 지속적인 요금이 청구되지 않도록 합니다.