목록 작업 사용

일부 서비스는 행 또는 리소스 설명과 같이 잠재적으로 큰 항목 목록을 반환합니다. CPU 및 메모리 사용량을 제어하기 위해 서비스는 이러한 리소스를 pages로 반환합니다. 즉, 다음 하위 집합을 요청하는 연속 토큰이 있는 더 작은 항목 하위 집합입니다.

페이지별로 항목을 반복하는 작업은 지루할 수 있습니다. 클라이언트 라이브러리는 페이지를 비동기 반복자로 변환하는 어댑터를 제공합니다. 이 가이드에서는 이러한 어댑터를 사용하는 방법을 보여줍니다.

기본 요건

이 가이드에서는 Secret Manager 서비스를 사용하여 목록 작업을 보여줍니다. 이 가이드에 포함된 개념은 다른 서비스에도 적용됩니다.

이 가이드를 따르려면 Secret Manager 서비스를 사용 설정하고 로그인한 후 계정에 필요한 권한이 있는지 확인해야 합니다. 이러한 기본 요건을 충족하는 방법에 대한 안내는 서비스 빠른 시작을 따르세요.

Rust 라이브러리의 전체 설정 안내는 개발 환경 설정을 참조하세요.

종속 항목

Cargo.toml 파일에 Secret Manager 라이브러리를 추가합니다.

cargo add google-cloud-secretmanager-v1

목록 메서드 반복

목록 메서드에서 항목을 반복하는 데 도움이 되도록 API는 ItemPaginator 특성의 구현을 반환합니다. use 선언을 사용하여 특성을 범위에 도입합니다.

use google_cloud_gax::paginator::ItemPaginator as _;

항목을 반복하려면 by_item 메서드를 사용합니다.

let mut list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_item();
while let Some(secret) = list.next().await {
    let secret = secret?;
    println!("  secret={}", secret.name)
}

드물지만 페이지에 액세스해야 하는 추가 정보가 포함되어 있거나 프로세스 전반에서 진행 상황을 체크포인트해야 할 수 있습니다. 필요한 경우 개별 항목 대신 전체 페이지를 반복할 수 있습니다.

  1. use 선언을 사용하여 Paginator를 범위에 도입합니다. 

    use google_cloud_gax::paginator::Paginator as _;

  2. by_page를 사용하여 페이지를 반복합니다. 

    let mut list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_page();
while let Some(page) = list.next().await {
    let page = page?;
    println!("  next_page_token={}", page.next_page_token);
    page.secrets
        .into_iter()
        .for_each(|secret| println!("    secret={}", secret.name));
}

futures::Stream 사용 중

tokio::Stream와 같은 비동기 스트림의 더 큰 Rust 생태계에서 이러한 API를 사용할 수 있습니다. 이 작업은 다음과 같이 수행할 수 있습니다.

  1. google_cloud_gax 크레이트에서 unstable-streams 기능을 사용 설정합니다. 이 기능의 이름은 이러한 API가 불안정하다는 것을 나타냅니다. futures::Stream 특성의 호환되지 않는 변경으로 인해 발생하는 중단을 처리할 준비가 된 경우에만 사용해야 합니다.

    cargo add google-cloud-gax --features unstable-stream

  2. 다음 예시에서는 futures 크레이트를 추가하여 사용 설정하는 futures::stream::StreamExt 특성도 사용합니다.

    cargo add futures

  3. 필수 use 선언을 추가합니다. 

    use futures::stream::StreamExt;
use google_cloud_gax::paginator::ItemPaginator as _;

  4. into_stream 함수를 사용하여 ItemPaginator를 futures::Stream로 변환합니다. 

    let list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_item()
    .into_stream();
list.map(|secret| -> gax::Result<()> {
    println!("  secret={}", secret?.name);
    Ok(())
})
.fold(Ok(()), async |acc, result| -> gax::Result<()> {
    acc.and(result)
})
.await?;

마찬가지로 into_stream 함수를 사용하여 Paginator를 futures::Stream로 변환할 수 있습니다.

let list = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .by_page()
    .into_stream();
list.enumerate()
    .map(|(index, page)| -> gax::Result<()> {
        println!("page={}, next_page_token={}", index, page?.next_page_token);
        Ok(())
    })
    .fold(Ok(()), async |acc, result| -> gax::Result<()> {
        acc.and(result)
    })
    .await?;

다음 페이지 토큰을 설정하여 목록 메서드 재개

목록 작업이 중단된 경우와 같은 일부 경우에는 다음 페이지 토큰을 설정하여 특정 페이지에서 페이지로 나누기를 재개할 수 있습니다.

let page = client
    .list_secrets()
    .set_parent(format!("projects/{project_id}"))
    .send()
    .await;
let page = page?;
let mut next_page_token = page.next_page_token.clone();
page.secrets
    .into_iter()
    .for_each(|secret| println!("    secret={}", secret.name));

while !next_page_token.is_empty() {
    println!("  next_page_token={next_page_token}");

    let page = client
        .list_secrets()
        .set_parent(format!("projects/{project_id}"))
        .set_page_token(next_page_token)
        .send()
        .await;
    let page = page?;
    next_page_token = page.next_page_token.clone();

    page.secrets
        .into_iter()
        .for_each(|secret| println!("    secret={}", secret.name));
}

페이지로 나누기 도우미를 사용해야 하는 경우

Google API 목록 메서드가 AIP-158에 정의된 페이지로 나누기 가이드라인을 따르는 경우 Rust용 Google Cloud 클라이언트 라이브러리는 AIP-4233에 정의된 목록 RPC를 ItemPaginator 및 Paginator를 구현하는 유형으로 변환하는 어댑터를 제공합니다. 간단히 말해 이 가이드라인에서는 List 메서드를 호출할 때마다 리소스 항목(예: 보안 비밀) 페이지와 함께 다음 페이지를 검색하기 위해 List 메서드에 전달할 수 있는 토큰을 반환해야 합니다.

대부분의 Google Cloud 서비스는 이러한 가이드라인을 따릅니다. 그렇지 않은 경우 자체 어댑터를 구현하여 결과를 반복해야 합니다.