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:
- Aktivieren Sie den Secret Manager-Dienst.
- Aktivieren Sie die Cloud Natural Language API.
- 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.
Versuchen Sie, eine neue Secret-Version zu erstellen:
Wenn
update_attempterfolgreich ist, wird das Ergebnis ausgegeben und zurückgegeben:Wenn
update_attemptfehlschlä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:Suchen Sie nach einem Fehler, der einem fehlenden Secret entspricht:
Wenn der Fehler „Nicht gefunden“ (
Code::NotFound) auftritt, versuchen Sie, das Secret zu erstellen:Versuchen Sie noch einmal, die Secret-Version hinzuzufügen. Dieses Mal wird ein Fehler zurückgegeben, wenn etwas fehlschlägt:
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.
Codebeispiel: Hilfsmethode (update_attempt)
Die Hilfsmethode update_attempt versucht, eine Secret-Version hinzuzufügen, und berechnet die CRC32c-Prüfsumme der Nutzlastdaten:
Codebeispiel: Hilfsmethode (create_secret)
Die Hilfsmethode create_secret erstellt ein fehlendes Secret und konfiguriert eine benutzerdefinierte Wiederholungsrichtlinie:
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.
Erstellen Sie einen Client:
Senden Sie eine Anfrage (in diesem Beispiel fehlt ein Schlüsselfeld):
Extrahieren Sie den Fehler mit Standard-Rust-Funktionen aus dem Ergebnis. Der Fehlertyp gibt alle Fehlerdetails in menschenlesbarer Form aus:
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:
Iterieren Sie über die Details:
Die Clientbibliotheken geben eine StatusDetails-Enum mit den verschiedenen Arten von Fehlerdetails zurück. In diesem Beispiel werden nur BadRequest-Fehler untersucht:
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:
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.
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:
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:
Alternativ entspricht der folgende Code der zweiten Vorlage:
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: