Google은 AI 기술을 사용하여 콘텐츠를 사용자의 기본 언어로 번역합니다. AI 번역에는 오류가 있을 수 있습니다.

오류 처리

오류를 사전에 해석하고 대응하여 보다 일관된 사용자 환경을 제공합니다. 자동화된 클라우드 워크플로를 개발하든 원격 API와 상호작용하든 Rust 클라이언트 라이브러리는 오류를 정상적으로 처리하는 방법을 제공합니다. 이 가이드에서는 다음 방법을 설명합니다.

오류 처리: 오류 유형을 검사하고 NotFound 오류가 발생할 때 누락된 리소스를 만드는 등 서비스 상태 코드를 기반으로 애플리케이션 로직을 분기합니다.
오류 세부정보 검사: 서비스에서 반환한 잘못된 요청 필드 위반 또는 할당량 실패와 같은 풍부한 오류 세부정보를 추출하고 검사하여 Google Cloud 서비스 API 문제를 해결하고 런타임 동작을 동적으로 조정합니다.
바인딩 오류 해결: 유효하지 않거나 누락된 요청 필드로 인해 발생하는 클라이언트 측 HTTP 바인딩 오류를 해석하고 해결하여 요청이 서비스에 원활하게 도달하도록 합니다.

기본 요건

이 가이드에서는 Secret Manager 서비스와 Cloud Natural Language API를 사용하여 오류 처리를 보여줍니다. 예시를 실행하려면 먼저 다음 단계를 따르세요.

Secret Manager 서비스를 사용 설정합니다.
Cloud Natural Language API를 사용 설정합니다.
인증을 설정합니다.

종속 항목

다음 명령어를 사용하여 필요한 종속 항목을 Cargo.toml 파일에 추가합니다.

cargo add google-cloud-secretmanager-v1 google-cloud-gax crc32c google-cloud-language-v2

오류 처리

Rust 클라이언트 라이브러리를 사용하면 오류를 표시하고 대응할 수 있습니다. 예를 들어 오류 검색을 사용하여 동작을 분기할 수 있습니다. 클라우드 서비스의 일반적인 패턴은 컨테이너가 있는 것처럼 리소스를 사용하고 오류가 발생한 경우에만 컨테이너를 만드는 것입니다. 컨테이너가 일반적으로 있는 경우 이 접근 방식은 요청을 하기 전에 컨테이너가 있는지 확인하는 것보다 더 효율적입니다.

다음 예시에서는 Secret Manager 보안 비밀을 업데이트하려고 할 때 오류를 포착하고 아직 없는 경우 보안 비밀을 만들어 누락된 리소스를 처리하는 방법을 보여줍니다.

새 보안 비밀 버전을 만들어 봅니다.

match update_attempt(&client, project_id, secret_id, data.clone()).await {

update_attempt가 성공하면 성공 결과를 출력하고 반환합니다.

Ok(version) => {
    println!("new version is {}", version.name);
    Ok(version)
}

update_attempt가 실패하면 실패 원인을 명확히 해야 합니다. 연결 끊김 또는 인증 토큰 오류와 같은 여러 가지 이유로 요청이 실패했을 수 있습니다. 재시도 정책은 이러한 오류 대부분을 처리할 수 있습니다. 서비스에서 반환된 오류를 찾습니다.
```
Err(e) => {
    if let Some(status) = e.downcast_ref::<Error>().and_then(|e| e.status()) {
```
누락된 보안 비밀에 해당하는 오류를 찾습니다.
```
if status.code == Code::NotFound {
```
'찾을 수 없음' 오류 (Code::NotFound)가 발생한 경우 보안 비밀을 만들어 봅니다.
```
let _ = create_secret(&client, project_id, secret_id).await?;
```

보안 비밀 버전을 다시 추가해 봅니다. 이번에는 실패하면 오류를 반환합니다.

let version = update_attempt(&client, project_id, secret_id, data).await?;
println!("new version is {}", version.name);
return Ok(version);

코드 샘플: 기본 함수 (`sample`)

이 예시의 전체 코드는 기본 오케스트레이션 함수 (sample)와 두 개의 도우미 메서드(update_attempt 및 create_secret)의 세 부분으로 나뉩니다.

sample 함수는 보안 비밀에 새 버전을 추가하려고 시도합니다. 클라이언트에서 반환된 오류를 포착하고 오류가 Code::NotFound 오류인지 확인합니다. 보안 비밀을 찾을 수 없으면 함수는 처음에 누락된 보안 비밀을 만들고 업데이트를 재시도합니다.

use google_cloud_gax::error::Error;
use google_cloud_gax::error::rpc::Code;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::SecretVersion;

pub async fn sample(
    project_id: &str,
    secret_id: &str,
    data: Vec<u8>,
) -> anyhow::Result<SecretVersion> {
    let client = SecretManagerService::builder().build().await?;

    match update_attempt(&client, project_id, secret_id, data.clone()).await {
        Ok(version) => {
            println!("new version is {}", version.name);
            Ok(version)
        }
        Err(e) => {
            if let Some(status) = e.downcast_ref::<Error>().and_then(|e| e.status()) {
                if status.code == Code::NotFound {
                    let _ = create_secret(&client, project_id, secret_id).await?;
                    let version = update_attempt(&client, project_id, secret_id, data).await?;
                    println!("new version is {}", version.name);
                    return Ok(version);
                }
            }
            Err(e)
        }
    }
}

코드 샘플: 도우미 메서드 (`update_attempt`)

도우미 메서드 update_attempt는 페이로드 데이터의 CRC32c 체크섬을 계산하여 보안 비밀 버전을 추가하려고 시도합니다.

use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::{SecretPayload, SecretVersion};

pub(crate) async fn update_attempt(
    client: &SecretManagerService,
    project_id: &str,
    secret_id: &str,
    data: Vec<u8>,
) -> anyhow::Result<SecretVersion> {
    let checksum = crc32c::crc32c(&data) as i64;
    let version = client
        .add_secret_version()
        .set_parent(format!("projects/{project_id}/secrets/{secret_id}"))
        .set_payload(
            SecretPayload::new()
                .set_data(data)
                .set_data_crc32c(checksum),
        )
        .send()
        .await?;
    Ok(version)
}

코드 샘플: 도우미 메서드 (`create_secret`)

도우미 메서드 create_secret은 누락된 보안 비밀을 만들고 맞춤 재시도 정책을 구성합니다.

use google_cloud_gax::options::RequestOptionsBuilder;
use google_cloud_gax::retry_policy::AlwaysRetry;
use google_cloud_gax::retry_policy::RetryPolicyExt;
use google_cloud_secretmanager_v1::client::SecretManagerService;
use google_cloud_secretmanager_v1::model::{Replication, Secret, replication};
use std::time::Duration;

pub async fn create_secret(
    client: &SecretManagerService,
    project_id: &str,
    secret_id: &str,
) -> anyhow::Result<Secret> {
    let secret = client
        .create_secret()
        .set_parent(format!("projects/{project_id}"))
        .with_retry_policy(
            AlwaysRetry
                .with_attempt_limit(5)
                .with_time_limit(Duration::from_secs(60)),
        )
        .set_secret_id(secret_id)
        .set_secret(
            Secret::new()
                .set_replication(Replication::new().set_replication(
                    replication::Replication::Automatic(replication::Automatic::new().into()),
                ))
                .set_labels([("integration-test", "true")]),
        )
        .send()
        .await?;
    Ok(secret)
}

오류 세부정보 검사

일부 Google Cloud 서비스에는 요청이 실패할 때 추가 오류 세부정보가 포함됩니다. 문제 해결을 지원하기 위해 Rust 클라이언트 라이브러리는 std::fmt::Display를 사용하여 오류를 형식화할 때 이러한 세부정보를 포함합니다. 이러한 세부정보를 검사하고 그에 따라 애플리케이션 동작을 변경할 수 있습니다.

서비스에서 반환된 오류에만 세부정보가 포함됩니다. 클라이언트 라이브러리는 다양한 유형의 오류 세부정보가 포함된 StatusDetails enum을 반환합니다.

오류 세부정보 추출

이 예시에서는 의도적으로 Cloud Natural Language API에 잘못된 요청을 보내고 결과 오류를 검사합니다.

클라이언트를 만듭니다.

let client = LanguageService::builder().build().await?;

요청을 보냅니다 (이 예시에서는 키 필드가 누락됨).

let result = client
    .analyze_sentiment()
    .set_document(
        Document::new()
            // Missing document contents
            // .set_content("Hello World!")
            .set_type(Type::PlainText),
    )
    .send()
    .await;

표준 Rust 함수를 사용하여 결과에서 오류를 추출합니다. 오류 유형은 사람이 읽을 수 있는 형식으로 모든 오류 세부정보를 출력합니다.
```
let err = result.expect_err("the request should have failed");
println!("\nrequest failed with error {err:#?}");
```

출력은 다음과 비슷합니다.

request failed with error Error {
    kind: Service {
        status_code: Some(
            400,
        ),
        headers: Some(
            {
                "vary": "X-Origin",
                "vary": "Referer",
                "vary": "Origin,Accept-Encoding",
                "content-type": "application/json; charset=UTF-8",
                "date": "Sat, 24 May 2025 17:19:49 GMT",
                "server": "scaffolding on HTTPServer2",
                "x-xss-protection": "0",
                "x-frame-options": "SAMEORIGIN",
                "x-content-type-options": "nosniff",
                "alt-svc": "h3=\":443\"; ma=2592000,h3-29=\":443\"; ma=2592000",
                "accept-ranges": "none",
                "transfer-encoding": "chunked",
            },
        ),
        status: Status {
            code: InvalidArgument,
            message: "One of content, or gcs_content_uri must be set.",
            details: [
                BadRequest(
                    BadRequest {
                        field_violations: [
                            FieldViolation {
                                field: "document.content",
                                description: "Must have some text content to annotate.",
                                reason: "",
                                localized_message: None,
                                _unknown_fields: {},
                            },
                        ],
                        _unknown_fields: {},
                    },
                ),
            ],
        },
    },
}

프로그래매틱 방식으로 오류 세부정보 검사

경우에 따라 프로그래매틱 방식으로 오류 세부정보를 검사해야 할 수 있습니다. 이 예시에서는 데이터 구조를 트래버스하고 가장 관련성이 높은 필드를 출력합니다.

서비스에서 반환된 오류에만 세부정보가 포함되므로 먼저 오류를 쿼리하여 올바른 오류 유형이 포함되어 있는지 확인합니다. 포함되어 있으면 오류에 관한 일부 최상위 정보를 분석할 수 있습니다.

if let Some(status) = err.status() {
    println!(
        "  status.code={}, status.message={}",
        status.code, status.message,
    );

세부정보를 반복합니다.

for detail in status.details.iter() {
    match detail {

앞서 언급했듯이 클라이언트 라이브러리는 다양한 유형의 오류 세부정보가 포함된 StatusDetails enum을 반환합니다. 이 예시에서는 BadRequest 오류만 검사합니다.

StatusDetails::BadRequest(bad) => {

BadRequest에는 위반된 필드 목록이 포함되어 있습니다. 각 세부정보를 반복하고 출력할 수 있습니다.

for f in bad.field_violations.iter() {
    println!(
        "  the request field {} has a problem: \"{}\"",
        f.field, f.description
    );
}

이러한 정보는 개발 중에 유용할 수 있습니다. StatusDetails와 같은 QuotaFailure의 다른 브랜치는 런타임에 애플리케이션을 제한하는 데 유용할 수 있습니다.

예상 출력

오류 세부정보의 출력은 다음과 비슷합니다.

  status.code=400, status.message=One of content, or gcs_content_uri must be set., status.status=Some("INVALID_ARGUMENT")
  the request field document.content has a problem: "Must have some text content to annotate."

코드 샘플: 오류 세부정보 검사

sample 함수는 서비스 오류를 생성하기 위해 의도적으로 Cloud Natural Language API에 유효하지 않은 요청을 보냅니다. 그런 다음 오류를 포착하고 프로그래매틱 방식으로 StatusDetails를 추출하여 특정 BadRequest 필드 위반을 검사하고 출력합니다.

use google_cloud_gax::error::rpc::StatusDetails;
use google_cloud_language_v2::client::LanguageService;
use google_cloud_language_v2::model::Document;
use google_cloud_language_v2::model::document::Type;

pub async fn sample() -> anyhow::Result<()> {
    let client = LanguageService::builder().build().await?;

    let result = client
        .analyze_sentiment()
        .set_document(
            Document::new()
                // Missing document contents
                // .set_content("Hello World!")
                .set_type(Type::PlainText),
        )
        .send()
        .await;

    let err = result.expect_err("the request should have failed");
    println!("\nrequest failed with error {err:#?}");

    if let Some(status) = err.status() {
        println!(
            "  status.code={}, status.message={}",
            status.code, status.message,
        );
        for detail in status.details.iter() {
            match detail {
                StatusDetails::BadRequest(bad) => {
                    for f in bad.field_violations.iter() {
                        println!(
                            "  the request field {} has a problem: \"{}\"",
                            f.field, f.description
                        );
                    }
                }
                _ => {
                    println!("  additional error details: {detail:?}");
                }
            }
        }
    }

    Ok(())
}

바인딩 오류 해결

HTTP를 사용하여 Google Cloud 서비스에 요청을 보낼 때 요청은 통합 리소스 식별자 (URI)를 사용하여 리소스를 지정합니다. 일부 RPC는 여러 URI에 해당하며 요청의 콘텐츠에 따라 사용되는 URI가 결정됩니다.

클라이언트 라이브러리는 가능한 모든 URI를 고려하고 작동하는 URI가 없는 경우에만 바인딩 오류를 반환합니다. 일반적으로 필드가 누락되었거나 형식이 잘못된 경우에 발생합니다.

요청이 가능한 URI의 유효한 형식이 포함된 필드를 제공하지 못하면 바인딩 오류가 발생할 수 있습니다.

Error: cannot find a matching binding to send the request: at least one of the
conditions must be met: (1) field `name` needs to be set and match the template:
'projects/*/secrets/*' OR (2) field `name` needs to be set and match the
template: 'projects/*/locations/*/secrets/*'

위의 예시 오류는 예시에서 이름을 제공하지 않고 리소스의 세부정보를 검색하려고 시도했기 때문에 발생했습니다. 특히 name 필드 GetSecretRequest 은 필수이지만 예시에서 설정하지 않았습니다.

let secret = client
    .get_secret()
    //.set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

바인딩 오류 해결 방법

오류를 해결하려면 오류 메시지에 표시된 템플릿 중 하나와 일치하도록 필수 필드를 설정합니다.

'projects/*/secrets/*'
'projects/*/locations/*/secrets/*'

두 템플릿 모두 클라이언트 라이브러리가 서버에 요청을 보낼 수 있도록 합니다. 예를 들어 다음 코드는 첫 번째 템플릿과 일치합니다.

let secret = client
    .get_secret()
    .set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

또는 다음 코드는 두 번째 템플릿과 일치합니다.

let secret = client
    .get_secret()
    .set_name("projects/my-project/locations/us-central1/secrets/my-secret")
    .send()
    .await;

템플릿 해석

바인딩 오류의 오류 메시지에는 요청 필드의 가능한 값을 보여주는 템플릿 문자열이 포함되어 있습니다. 대부분의 템플릿 문자열에는 * 및 **가 필드 값과 일치하는 와일드 카드로 포함되어 있습니다.

단일 와일드 카드

* 와일드 카드는 /가 없는 비어 있지 않은 문자열을 의미합니다. 정규 표현식 [^/]+로 생각할 수 있습니다.

예를 들면 다음과 같습니다.

템플릿	입력	일치
`*`	`simple-string-123`	`true`
`projects/*`	`projects/p`	`true`
`projects/*/locations`	`projects/p/locations`	`true`
`projects//locations/`	`projects/p/locations/l`	`true`
`*`	`""` (비어 있음)	`false`
`*`	`string/with/slashes`	`false`
`projects/*`	`projects/` (비어 있음)	`false`
`projects/*`	`projects/p/` (추가 슬래시)	`false`
`projects/*`	`projects/p/locations/l`	`false`
`projects/*/locations`	`projects/p`	`false`
`projects/*/locations`	`projects/p/locations/l`	`false`

이중 와일드 카드

덜 일반적인 것은 모든 문자열을 의미하는 ** 와일드 카드입니다. 문자열은 비어 있거나 슬래시 (/)를 포함할 수 있습니다. 정규 표현식 .*로 생각할 수 있습니다.

템플릿이 /**로 끝나면 초기 슬래시는 선택사항입니다.

템플릿	입력	일치
`**`	`""`	`true`
`**`	`simple-string-123`	`true`
`**`	`string/with/slashes`	`true`
`projects//*`	`projects/p`	`true`
`projects//*`	`projects/p/locations`	`true`
`projects//*`	`projects/p/locations/l`	`true`
`projects//*`	`locations/l`	`false`
`projects//*`	`projects//locations/l`	`false`

바인딩 오류 검사

프로그래매틱 방식으로 오류를 검사해야 하는 경우 바인딩 오류인지 확인하고 BindingError로 다운캐스팅합니다.

let secret = client
    .get_secret()
    //.set_name("projects/my-project/secrets/my-secret")
    .send()
    .await;

let e = secret.unwrap_err();
assert!(e.is_binding(), "{e:?}");
assert!(e.source().is_some(), "{e:?}");
let _ = e
    .source()
    .and_then(|e| e.downcast_ref::<BindingError>())
    .expect("should be a BindingError");

다음 단계

재시도 정책 구성에 대해 알아봅니다.

오류 처리 컬렉션을 사용해 정리하기 내 환경설정을 기준으로 콘텐츠를 저장하고 분류하세요.

기본 요건

종속 항목

오류 처리

코드 샘플: 기본 함수 (sample)

코드 샘플: 도우미 메서드 (update_attempt)

코드 샘플: 도우미 메서드 (create_secret)

오류 세부정보 검사

오류 세부정보 추출

프로그래매틱 방식으로 오류 세부정보 검사

예상 출력

코드 샘플: 오류 세부정보 검사

바인딩 오류 해결

바인딩 오류 해결 방법

템플릿 해석

단일 와일드 카드

이중 와일드 카드

바인딩 오류 검사

다음 단계

오류 처리

코드 샘플: 기본 함수 (`sample`)

코드 샘플: 도우미 메서드 (`update_attempt`)

코드 샘플: 도우미 메서드 (`create_secret`)