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 シークレットの更新を試行したときにエラーをキャッチし、存在しない場合は作成することで、不足しているリソースを処理する方法を示しています。

新しい Secret バージョンを作成してみます。

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()) {
```
不足している Secret に対応するエラーを探します。
```
if status.code == Code::NotFound {
```
「見つからない」エラー（Code::NotFound）が発生した場合は、Secret の作成を試みます。
```
let _ = create_secret(&client, project_id, secret_id).await?;
```

Secret バージョンをもう一度追加してみてください。今回は、失敗した場合はエラーを返します。

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

コードサンプル: メイン関数（`sample`）

この例の完全なコードは、メインオーケストレーション関数（sample）と、その 2 つのヘルパーメソッド（update_attempt と create_secret）の 3 つの部分に分かれています。

sample 関数は、Secret に新しいバージョンを追加しようとします。クライアントから返されたエラーをキャッチし、エラーが Code::NotFound エラーかどうかを確認します。Secret が見つからない場合、関数は最初に不足していた Secret を作成し、更新を再試行します。

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 は、Secret バージョンを追加しようとし、ペイロードデータの 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 は、不足している 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 列挙型を返します。

エラーの詳細を抽出する

この例では、 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 列挙型を返します。この例では、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 サービスにリクエストを送信する場合、リクエストは Uniform Resource Identifier（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;

または、次のコードは 2 番目のテンプレートと一致します。

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`

2 個のワイルドカード

あまり一般的ではありませんが、** ワイルドカードは任意の文字列を意味します。文字列は空にすることも、任意の数のスラッシュ（/）を含めることもできます。正規表現 .*と考えることができます。

テンプレートが /** で終わる場合、最初のスラッシュは省略可能です。

テンプレート	入力	照合しますか？
`**`	`""`	`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");

次のステップ

再試行ポリシーの構成について学習する。