Fehlerbehandlung

Sorgen Sie für eine einheitlichere Nutzererfahrung, indem Sie Fehler proaktiv interpretieren und darauf reagieren. Unabhängig davon, ob Sie automatisierte Cloud-Workflows entwickeln oder mit Remote-APIs interagieren, bieten die Rust-Clientbibliotheken Möglichkeiten, Fehler ordnungsgemäß zu verarbeiten. In diesem Dokument wird Folgendes erläutert:

  • Fehler verarbeiten: Prüfen Sie Fehlertypen und verzweigen Sie Ihre Anwendungslogik basierend auf Dienststatuscodes, z. B. durch Erstellen einer fehlenden Ressource, wenn ein NotFound-Fehler auftritt.
  • Fehlerdetails prüfen: Extrahieren Sie umfangreiche Fehlerdetails wie Verstöße gegen Felder für fehlerhafte Anfragen oder Kontingentfehler aus Google Cloud -Diensten, um API-Probleme zu beheben und das Laufzeitverhalten anzupassen.
  • Bindungsfehler beheben: Interpretieren und beheben Sie clientseitige HTTP-Bindungsfehler, die durch ungültige oder fehlende Anfragefelder verursacht werden, damit Ihre Anfragen den Dienst problemlos erreichen.

Vorbereitung

In diesem Dokument werden der Secret Manager-Dienst und die Cloud Natural Language API verwendet, um die Fehlerbehandlung zu veranschaulichen. So führen Sie die Beispiele aus:

  1. Aktivieren Sie den Secret Manager-Dienst.
  2. Aktivieren Sie die Cloud Natural Language API.
  3. Richten Sie die Authentifizierung ein.

Abhängigkeiten

Verwenden Sie den folgenden Befehl, um die erforderlichen Abhängigkeiten zu Ihrer Cargo.toml-Datei hinzuzufügen:

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

Fehler verarbeiten

Mit den Rust-Clientbibliotheken können Sie Fehler anzeigen und darauf reagieren. Sie können beispielsweise die Fehlererkennung verwenden, um das Verhalten zu verzweigen. Ein gängiges Muster bei Cloud-Diensten besteht darin, eine Ressource so zu verwenden, als ob ihr Container vorhanden wäre, und den Container nur dann zu erstellen, wenn ein Fehler auftritt. Wenn der Container normalerweise vorhanden ist, ist dieser Ansatz effizienter, als vor der Anfrage zu prüfen, ob der Container vorhanden ist.

Im folgenden Beispiel wird der Fehler beim Aktualisieren eines Secret Manager-Secrets abgefangen und das Secret erstellt, wenn es nicht vorhanden ist.

  1. Versuchen Sie, eine neue Secret-Version zu erstellen:

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

  2. Wenn update_attempt erfolgreich ist, wird das Ergebnis ausgegeben und zurückgegeben:

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

  3. Wenn update_attempt fehlschlägt, müssen Sie die Ursache des Fehlers ermitteln. Die Anfrage kann aus vielen Gründen fehlgeschlagen sein, z. B. aufgrund einer unterbrochenen Verbindung oder eines Fehlers bei Authentifizierungstokens. Wiederholungsrichtlinien können die meisten dieser Fehler beheben. Suchen Sie nach Fehlern, die vom Dienst zurückgegeben werden:

    Err(e) => {
        if let Some(status) = e.downcast_ref::<Error>().and_then(|e| e.status()) {

  4. Suchen Sie nach einem Fehler, der einem fehlenden Secret entspricht:

    if status.code == Code::NotFound {

  5. Wenn der Fehler „Nicht gefunden“ (Code::NotFound) auftritt, versuchen Sie, das Secret zu erstellen:

    let _ = create_secret(&client, project_id, secret_id).await?;

  6. Versuchen Sie noch einmal, die Secret-Version hinzuzufügen. Dieses Mal wird ein Fehler zurückgegeben, wenn etwas fehlschlägt:

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

Codebeispiel: Hauptfunktion (sample)

Der vollständige Code für dieses Beispiel ist in drei Teile unterteilt: die Hauptorchestrierungsfunktion (sample), gefolgt von den beiden Hilfsmethoden (update_attempt und create_secret).

Die Funktion sample versucht, einem Secret eine neue Version hinzuzufügen. Der vom Client zurückgegebene Fehler wird abgefangen und es wird geprüft, ob es sich um einen Code::NotFound-Fehler handelt. Wenn das Secret nicht gefunden wird, erstellt die Funktion das fehlende Secret und versucht, das Update noch einmal auszuführen.

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

Codebeispiel: Hilfsmethode (update_attempt)

Die Hilfsmethode update_attempt versucht, eine Secret-Version hinzuzufügen, und berechnet die CRC32c-Prüfsumme der Nutzlastdaten:

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

Codebeispiel: Hilfsmethode (create_secret)

Die Hilfsmethode create_secret erstellt ein fehlendes Secret und konfiguriert eine benutzerdefinierte Wiederholungsrichtlinie:

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

Fehlerdetails prüfen

Einige Google Cloud -Dienste enthalten zusätzliche Fehlerdetails, wenn Anfragen fehlschlagen. Zur Unterstützung bei der Fehlerbehebung enthalten die Rust-Clientbibliotheken diese Details, wenn Fehler mit std::fmt::Display formatiert werden. Sie können diese Details prüfen und das Verhalten Ihrer Anwendung entsprechend ändern.

Nur vom Dienst zurückgegebene Fehler enthalten detaillierte Informationen. Die Clientbibliotheken geben eine StatusDetails-Aufzählung mit den verschiedenen Arten von Fehlerdetails zurück.

Fehlerdetails extrahieren

In diesem Beispiel wird absichtlich eine fehlerhafte Anfrage an die Cloud Natural Language API gesendet und der resultierende Fehler untersucht.

  1. Erstellen Sie einen Client:

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

  2. Senden Sie eine Anfrage (in diesem Beispiel fehlt ein Schlüsselfeld):

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

  3. Extrahieren Sie den Fehler mit Standard-Rust-Funktionen aus dem Ergebnis. Der Fehlertyp gibt alle Fehlerdetails in menschenlesbarer Form aus:

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

Die Ausgabe sieht etwa so aus:

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: {},
                    },
                ),
            ],
        },
    },
}

Fehlerdetails programmatisch prüfen

Manchmal müssen Sie die Fehlerdetails programmgesteuert prüfen. In diesem Beispiel wird die Datenstruktur durchlaufen und die relevantesten Felder werden ausgegeben.

Nur vom Dienst zurückgegebene Fehler enthalten detaillierte Informationen. Fragen Sie daher zuerst den Fehler ab, um zu sehen, ob er den richtigen Fehlertyp enthält. Wenn ja, können Sie einige allgemeine Informationen zum Fehler aufschlüsseln:

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

Iterieren Sie über die Details:

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

Die Clientbibliotheken geben eine StatusDetails-Enum mit den verschiedenen Arten von Fehlerdetails zurück. In diesem Beispiel werden nur BadRequest-Fehler untersucht:

StatusDetails::BadRequest(bad) => {

Ein BadRequest enthält eine Liste von Feldern, die gegen die Richtlinien verstoßen. Sie können die Details für jedes Dokument iterieren und ausgeben:

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

Diese Informationen können während der Entwicklung nützlich sein. Andere Zweige von StatusDetails, z. B. QuotaFailure, können zur Laufzeit nützlich sein, um eine Anwendung zu drosseln.

Erwartete Ausgabe

Die Ausgabe der Fehlerdetails sieht in etwa so aus:

  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."

Codebeispiel: Fehlerdetails prüfen

Die Funktion sample sendet eine absichtlich ungültige Anfrage an die Cloud Natural Language API, um einen Dienstfehler zu generieren. Anschließend wird der Fehler abgefangen und die StatusDetails wird programmatisch extrahiert, um bestimmte BadRequest-Feldverstöße zu prüfen und auszugeben.

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

Bindungsfehler beheben

Wenn Sie HTTP verwenden, um Anfragen an Google Cloud -Dienste zu senden, wird in der Anfrage ein Uniform Resource Identifier (URI) verwendet, um eine Ressource anzugeben. Einige RPCs entsprechen mehreren URIs. Der Inhalt der Anfrage bestimmt, welcher URI verwendet wird.

Die Clientbibliothek berücksichtigt alle möglichen URIs und gibt nur dann einen Bindungsfehler zurück, wenn keine URIs funktionieren. Das ist normalerweise der Fall, wenn ein Feld fehlt oder ein ungültiges Format hat.

Wenn Ihre Anfrage keine Felder mit einem gültigen Format für einen möglichen URI enthält, kann ein Bindungsfehler auftreten:

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/*'

Der vorherige Beispielfehler ist aufgetreten, weil im Beispiel versucht wird, die Details einer Ressource abzurufen, ohne ihren Namen anzugeben. Insbesondere ist das Feld name für ein GetSecretRequest erforderlich, wird im Beispiel aber nicht festgelegt:

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

Bindungsfehler beheben

Legen Sie das Pflichtfeld so fest, dass es einer der in der Fehlermeldung angezeigten Vorlagen entspricht, um den Fehler zu beheben:

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

Beide Vorlagen ermöglichen es der Clientbibliothek, eine Anfrage an den Server zu senden. Der folgende Code entspricht beispielsweise der ersten Vorlage:

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

Alternativ entspricht der folgende Code der zweiten Vorlage:

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

Dolmetschervorlagen

Die Fehlermeldung für einen Bindungsfehler enthält Vorlagenstrings, die mögliche Werte für die Anfragefelder zeigen. Die meisten Vorlagenstrings enthalten * und ** als Platzhalter, die mit den Feldwerten übereinstimmen.

Einzelner Platzhalter

Der Platzhalter * allein bedeutet einen nicht leeren String ohne /. Er kann als regulärer Ausdruck [^/]+ betrachtet werden.

Hier sind einige Beispiele:

Vorlage Eingabe Übereinstimmung?
* simple-string-123 true
projects/* projects/p true
projects/*/locations projects/p/locations true
projects/*/locations/* projects/p/locations/l true
* "" (leer) false
* string/with/slashes false
projects/* projects/ (leer) false
projects/* projects/p/ (zusätzlicher Schrägstrich) false
projects/* projects/p/locations/l false
projects/*/locations projects/p false
projects/*/locations projects/p/locations/l false

Doppelter Platzhalter

Weniger gebräuchlich ist der Platzhalter **, der für einen beliebigen String steht. Der String kann leer sein oder eine beliebige Anzahl von Schrägstrichen (/) enthalten. Er kann als regulärer Ausdruck .* betrachtet werden.

Wenn eine Vorlage mit /** endet, ist der Schrägstrich am Anfang optional.

Vorlage Eingabe Übereinstimmung?
** "" 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

Bindungsfehler prüfen

Wenn Sie den Fehler programmatisch prüfen müssen, prüfen Sie, ob es sich um einen Bindungsfehler handelt, und wandeln Sie ihn in einen BindingError um:

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

Nächste Schritte