목록 작업 사용

일부 서비스는 행 또는 리소스 설명과 같이 잠재적으로 큰 항목 목록을 반환합니다. 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::stream::StreamExt 특성도 사용합니다. 이 특성은 futures 크레이트를 추가하여 사용 설정합니다.

    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));
}

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

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

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