Google verwendet KI-Technologie, um Inhalte in Ihre bevorzugte Sprache zu übersetzen. KI-Übersetzungen können Fehler enthalten.

API-Fehler verstehen

In diesem Leitfaden wird erläutert, wie die Data Manager API Fehler behandelt und kommuniziert. Es ist wichtig, die Struktur und Bedeutung von API-Fehlern zu verstehen, um robuste Anwendungen zu entwickeln, die Probleme wie ungültige Eingaben oder vorübergehende Dienstausfälle problemlos bewältigen können.

Die Data Manager API folgt dem Standard-Fehlermodell von Google APIs, das basiert auf gRPC-Statuscodes. Jede API-Antwort, die zu einem Fehler führt, enthält ein Status-Objekt mit folgenden Informationen:

Ein numerischer Fehlercode.
Eine Fehlermeldung.
Optionale, zusätzliche Fehlerdetails.

Kanonische Fehlercodes

Die Data Manager API verwendet eine Reihe kanonischer Fehlercodes, die von gRPC und HTTP definiert werden. Diese Codes geben einen allgemeinen Hinweis auf den Fehlertyp. Sie sollten diesen Code immer zuerst prüfen, um die grundlegende Art des Problems zu verstehen.

Weitere Informationen zu diesen Codes finden Sie im Leitfaden zum API-Design unter Fehler codes.

Fast-Fail-Modell

Die Data Manager API verwendet ein Fast-Fail-Modell. Wenn eine Anfrage Strukturfehler enthält oder die Validierung eines Pflichtfelds für einen Datensatz fehlschlägt, schlägt die gesamte Anfrage fehl und die API verarbeitet keine Daten in dieser Anfrage.

Das Fast-Fail-Modell unterscheidet sich vom Modell für teilweise Fehler in einigen anderen Google APIs wie der Google Ads API und der Campaign Manager 360 API. Beim Modell für teilweise Fehler ist eine Anfrage auch dann erfolgreich, wenn einige Datensätze Fehler enthalten. Die Antwort enthält Fehlerdetails für die fehlgeschlagenen Datensätze.

Teilweise Fehler können zwar praktisch sein, bergen aber erhebliche Risiken, da Sie beim Modell für teilweise Fehler nicht proaktiv auf Fehler aufmerksam gemacht werden. Sie müssen jede Antwort explizit auf Fehler prüfen. Dadurch können wichtige Probleme verborgen bleiben, da eine Anfrage auch dann erfolgreich ist, wenn die API viele oder sogar alle Datensätze in der Anfrage ablehnt. Wenn ein erheblicher Teil der Datensätze in einer Anfrage Fehler enthält, Sie die Antwort aber nicht prüfen, sind Sie sich möglicherweise nicht bewusst, dass es weit verbreitete Probleme mit Ihren Daten gibt. Sie stellen diese Probleme erst Tage oder Wochen später fest, wenn die kumulativen Ergebnisse nicht Ihren Erwartungen entsprechen.

Das Fast-Fail-Modell vermeidet diese Fallstricke, indem Sie sofort auf Probleme mit Ihren Daten oder der Integration aufmerksam gemacht werden, damit Sie entsprechende Maßnahmen ergreifen können.

Fehler verarbeiten

Führen Sie die folgenden Schritte aus, wenn eine Anfrage fehlschlägt:

Prüfen Sie den Fehlercode, um den Fehlertyp zu ermitteln.
- Wenn Sie gRPC verwenden, befindet sich der Fehlercode im code Feld des Status. Wenn Sie eine Clientbibliothek verwenden, kann sie eine bestimmte Art von Ausnahme auslösen, die dem Fehlercode entspricht. Die Clientbibliothek für Java löst beispielsweise eine com.google.api.gax.rpc.InvalidArgumentException aus, wenn der Fehlercode INVALID_ARGUMENT ist.
- Wenn Sie REST verwenden, befindet sich der Fehlercode in der Fehlerantwort unter error.status und der entsprechende HTTP-Status unter error.code.
Wichtig: Die Data Manager API verwendet ein Fast-Fail-Modell. Wenn eine Anfrage fehlschlägt, werden keine Daten verarbeitet. Beheben Sie den Fehler und senden Sie die gesamte Anfrage noch einmal.
Suchen Sie nach der Standardnutzlast mit Details für den Fehlercode. Die Standardnutzlasten mit Details sind eine Reihe von Nachrichten für Fehler von Google APIs. Sie enthalten Fehlerdetails auf strukturierte und konsistente Weise. Jeder Fehler der Data Manager API kann mehrere Standardnutzlasten mit Details enthalten. Die Clientbibliotheken der Data Manager API enthalten Hilfsmethoden, um die Standardnutzlasten mit Details aus einem Fehler abzurufen.

Unabhängig vom Fehlercode empfehlen wir, nach den Nutzlasten ErrorInfo, RequestInfo, Help, und LocalizedMessage zu suchen und sie zu protokollieren.
- ErrorInfo enthält Informationen, die möglicherweise nicht in anderen Nutzlasten enthalten sind.
- RequestInfo enthält die Anfrage-ID, die hilfreich ist, wenn Sie sich an den Support wenden müssen.
- Help und LocalizedMessage enthalten Links und andere Details, die Ihnen bei der Behebung des Fehlers helfen.
Außerdem ist die Nutzlast BadRequest für INVALID_ARGUMENT-Fehler nützlich, da sie Informationen dazu enthält, welche Felder den Fehler verursacht haben.

Aufnahmewarnungen

Die Data Manager API akzeptiert so viel wie möglich von einer Aufnahmeanfrage. Wenn Sie nicht erforderliche Daten einfügen, führen Validierungsfehler für diese Felder nicht dazu, dass die Anfrage fehlschlägt. Wenn beispielsweise in einem Warenkorbartikel die Händlerprodukt-ID fehlt, verarbeitet die API den Rest der Anfrage und gibt eine Warnung zurück.

Eine erfolgreiche Aufnahmeanfrage (HTTP-Statuscode 200) enthält diese Warnungen in einer field_warnings-Liste. Jeder Eintrag ist ein FieldWarning-Objekt mit den folgenden Feldern:

field

Die Position des Felds in der Anfrage in der Pfadsyntax mit Unterstrichen.

Wenn ein Pfad auf ein Element in einer Liste (ein repeated-Feld) verweist, wird der Index in eckigen Klammern ([...]) nach dem Namen der Liste angezeigt.

events.events[0].cart_data.items[0].merchant_product_id gibt beispielsweise eine Warnung an, die sich auf das erste Element in den Warenkorbdaten des ersten Ereignisses in der Anfrage bezieht.

description

Eine Erklärung, warum der angegebene Wert eine Warnung verursacht hat.

reason

Der WarningReason Enum-Wert, der den Typ der Warnung angibt.

Beispiel mit `FieldWarning`

Hier sehen Sie eine Beispielantwort für eine erfolgreiche Aufnahmeanfrage, die eine Warnung enthält, weil für einen der Warenkorbartikel eine Händlerprodukt-ID gefehlt hat.

{
  "requestId": "126365e1-16d0-4c81-9de9-f362711e250a",
  "fieldWarnings": [
    {
      "field": "events.events[0].cart_data.items[0].merchant_product_id",
      "description": "The merchant product ID is missing in the cart item.",
      "reason": "WARNING_REASON_CART_DATA_ITEM_MERCHANT_PRODUCT_ID_MISSING"
    }
  ]
}

Standardnutzlasten mit Details

Die häufigsten Standardnutzlasten mit Details für die Data Manager API sind:

BadRequest
RequestInfo
ErrorInfo
Help und LocalizedMessage

`BadRequest`

Suchen Sie nach der BadRequest Nutzlast, wenn eine Anfrage mit INVALID_ARGUMENT fehlschlägt (HTTP-Statuscode 400).

Eine BadRequest-Nachricht zeigt an, dass die Anfrage Felder mit ungültigen Werten enthielt oder ein Wert für ein Pflichtfeld fehlte. Prüfen Sie die Liste field_violations in BadRequest, um herauszufinden, welche Felder Fehler enthalten. Jeder Eintrag in field_violations enthält Informationen, die Ihnen bei der Behebung des Fehlers helfen:

field

Die Position des Felds in der Anfrage in der Pfadsyntax mit Unterstrichen.

Wenn ein Pfad auf ein Element in einer Liste (ein repeated-Feld) verweist, wird der Index in eckigen Klammern ([...]) nach dem Namen der Liste angezeigt.

destinations[0].operating_account.account_id ist beispielsweise die account_id im operating_account des ersten Elements in der destinations Liste.

description

Eine Erklärung, warum der Wert einen Fehler verursacht hat.

reason

Die ErrorReason Enum, z. B. INVALID_HEX_ENCODING oder INVALID_CURRENCY_CODE.

Beispiele für `BadRequest`

Hier sehen Sie eine Beispielantwort für einen INVALID_ARGUMENT-Fehler mit einer BadRequest-Nachricht. Die field_violations zeigen, dass der Fehler eine accountId ist, die keine Zahl ist. Der Wert field destinations[0].login_account.account_id zeigt, dass sich die accountId mit einem Feldfehler im login_account des ersten Elements in der Liste destinations befindet.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-a8896317-069f-4198-afed-182a3872a660"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "destinations[0].login_account.account_id",
            "description": "String is not a valid number.",
            "reason": "INVALID_NUMBER_FORMAT"
          }
        ]
      }
    ]
  }
}

Hier sehen Sie ein weiteres Beispiel für eine Antwort von einem INVALID_ARGUMENT-Fehler mit einer BadRequest-Nachricht. In diesem Fall enthält die Liste field_violations zwei Fehler:

Das erste event hat einen Wert, der nicht hexadezimal codiert ist, in der zweiten Nutzer-ID des Ereignisses.
Das zweite event hat einen Wert, der nicht hexadezimal codiert ist, in der dritten Nutzer-ID des Ereignisses.

{
  "error": {
    "code": 400,
    "message": "There was a problem with the request.",
    "status": "INVALID_ARGUMENT",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "INVALID_ARGUMENT",
        "domain": "datamanager.googleapis.com",
        "metadata": {
          "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
        }
      },
      {
        "@type": "type.googleapis.com/google.rpc.RequestInfo",
        "requestId": "t-6bc8fb83-d648-4942-9c49-2604276638d8"
      },
      {
        "@type": "type.googleapis.com/google.rpc.BadRequest",
        "fieldViolations": [
          {
            "field": "events.events[0].user_data.user_identifiers[1]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          },
          {
            "field": "events.events[1].user_data.user_identifiers[2]",
            "description": "The HEX encoded value is malformed.",
            "reason": "INVALID_HEX_ENCODING"
          }
        ]
      }
    ]
  }
}

`RequestInfo`

Suchen Sie immer nach der RequestInfo Nutzlast, wenn eine Anfrage fehlschlägt. Eine RequestInfo enthält die request_id, die Ihre API-Anfrage eindeutig identifiziert.

{
  "@type": "type.googleapis.com/google.rpc.RequestInfo",
  "requestId": "t-4490c640-dc5d-4c28-91c1-04a1cae0f49f"
}

Wenn Sie Fehler protokollieren oder sich an den Support wenden, geben Sie unbedingt die Anfrage-ID an, um die Diagnose von Problemen zu erleichtern.

`ErrorInfo`

Suchen Sie nach der Nachricht ErrorInfo, um zusätzliche Informationen abzurufen, die möglicherweise nicht in den anderen Standardnutzlasten mit Details erfasst werden. Die Nutzlast ErrorInfo enthält eine metadata-Map mit Informationen zum Fehler.

Hier sehen Sie beispielsweise die ErrorInfo für einen PERMISSION_DENIED-Fehler, der durch die Verwendung von Anmeldedaten für ein Google Cloud-Projekt verursacht wurde, in dem die Data Manager API nicht aktiviert ist. Die ErrorInfo enthält zusätzliche Informationen zum Fehler, z. B.:

Das mit der Anfrage verknüpfte Projekt unter metadata.consumer.
Der Name des Dienstes unter metadata.serviceTitle.
Die URL, unter der der Dienst aktiviert werden kann, unter metadata.activationUrl.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "SERVICE_DISABLED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "service": "datamanager.googleapis.com",
          "containerInfo": "PROJECT_NUMBER",
          "serviceTitle": "Data Manager API",
          "activationUrl": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
        }
      },
      ...
    ]
  }
}

`Help` und `LocalizedMessage`

Suchen Sie nach den Nutzlasten Help und LocalizedMessage, um Links zu Dokumentation und lokalisierte Fehlermeldungen zu erhalten, die Ihnen helfen, den Fehler zu verstehen und zu beheben.

Hier sehen Sie beispielsweise die Nutzlasten Help und LocalizedMessage für einen PERMISSION_DENIED-Fehler, der durch die Verwendung von Anmeldedaten für ein Google Cloud-Projekt verursacht wurde, in dem die Data Manager API nicht aktiviert ist. Die Nutzlast Help enthält die URL, unter der der Dienst aktiviert werden kann, und die Nutzlast LocalizedMessage enthält eine Beschreibung des Fehlers.

{
  "error": {
    "code": 403,
    "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry.",
    "status": "PERMISSION_DENIED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.LocalizedMessage",
        "locale": "en-US",
        "message": "Data Manager API has not been used in project PROJECT_NUMBER before or it is disabled. Enable it by visiting https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER then retry. If you enabled this API recently, wait a few minutes for the action to propagate to our systems and retry."
      },
      {
        "@type": "type.googleapis.com/google.rpc.Help",
        "links": [
          {
            "description": "Google API Console API activation",
            "url": "https://console.cloud.google.com/apis/api/datamanager.googleapis.com/overview?project=PROJECT_NUMBER"
          }
        ]
      },
      ...
    ]
  }
}

Details zu Zugriffsfehlern

Wenn Sie eine der Clientbibliotheken verwenden, verwenden Sie die Hilfsmethoden, um die Standardnutzlasten mit Details abzurufen.

.NET

try {
    // Send API request
}
catch (Grpc.Core.RpcException rpcException)
{
    Console.WriteLine($"Exception encountered: {rpcException.Message}");
    var statusDetails =
        Google.Api.Gax.Grpc.RpcExceptionExtensions.GetAllStatusDetails(
            rpcException
        );
    foreach (var detail in statusDetails)
    {
        if (detail is Google.Rpc.BadRequest)
        {
            Google.Rpc.BadRequest badRequest = (Google.Rpc.BadRequest)detail;
            foreach (
                BadRequest.Types.FieldViolation? fieldViolation in badRequest.FieldViolations
            )
            {
                // Access attributes such as fieldViolation!.Reason and fieldViolation!.Field
            }
        }
        else if (detail is Google.Rpc.RequestInfo)
        {
            Google.Rpc.RequestInfo requestInfo = (Google.Rpc.RequestInfo)detail;
            string requestId = requestInfo.RequestId;
            // Log the requestId...
        }
        else if (detail is Google.Rpc.ErrorInfo)
        {
            Google.Rpc.ErrorInfo errorInfo = (Google.Rpc.ErrorInfo)detail;
            // Log the errorInfo.Reason and errorInfo.Metadata...

            // Log the details in the 'Metadata' map...
            foreach (
                KeyValuePair<String, String> metadataEntry in errorInfo.Metadata
            )
            {
                // Log the metadataEntry.Key and metadataEntry.Value...
            }
        }
        else
        {
            // ...
        }
    }
}

Java

try {
  // Send API request
} catch (com.google.api.gax.rpc.InvalidArgumentException invalidArgumentException) {
  // Gets the standard BadRequest payload from the exception.
  BadRequest badRequest = invalidArgumentException.getErrorDetails().getBadRequest();
  for (int i = 0; i < badRequest.getFieldViolationsCount(); i++) {
    FieldViolation fieldViolation = badRequest.getFieldViolations(i);
    // Access attributes such as fieldViolation.getField() and fieldViolation.getReason()
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
} catch (com.google.api.gax.rpc.ApiException apiException) {
  // Fallback exception handler for other types of ApiException.

  // Gets the standard ErrorInfo payload from the exception.
  ErrorInfo errorInfo = apiException.getErrorDetails().getErrorInfo();
  // Log the 'reason' and 'domain'...

  // Log the details in the 'metadata' map...
  for (Entry<String, String> metadataEntry : errorInfo.getMetadataMap().entrySet()) {
    // Log the metadataEntry key and value...
  }

  // Gets the standard RequestInfo payload from the exception.
  RequestInfo requestInfo = invalidArgumentException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

Best Practices für die Fehlerbehandlung

Implementieren Sie die folgenden Best Practices, um robuste Anwendungen zu entwickeln.

Fehlerdetails prüfen

Suchen Sie immer nach einer der Standardnutzlasten mit Details wie BadRequest. Jede Standardnutzlast mit Details enthält Informationen, die Ihnen helfen, die Ursache des Fehlers zu verstehen.

Zwischen Client- und Serverfehlern unterscheiden

Ermitteln Sie, ob der Fehler durch ein Problem mit Ihrer Implementierung (dem Client) oder mit der API (dem Server) verursacht wird.

Clientfehler: Codes wie INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Diese erfordern Änderungen an der Anfrage oder am Status/den Anmeldedaten Ihrer Anwendung. Wiederholen Sie die Anfrage nicht, ohne das Problem zu beheben.
Serverfehler: Codes wie UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Diese deuten auf ein vorübergehendes Problem mit dem API-Dienst hin.

Wiederholungsstrategie implementieren

Ermitteln Sie, ob der Fehler wiederholt werden kann, und verwenden Sie eine Wiederholungsstrategie.

Wiederholen Sie den Vorgang nur bei vorübergehenden Serverfehlern wie UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN und ABORTED.
Verwenden Sie einen exponentiellen Backoff-Algorithmus, um die Wartezeiten zwischen den Wiederholungen zu verlängern. So vermeiden Sie, dass ein bereits überlasteter Dienst überfordert wird. Warten Sie beispielsweise 1 Sekunde, dann 2 Sekunden, dann 4 Sekunden usw. bis zu einer maximalen Anzahl von Wiederholungen oder einer maximalen Wartezeit.
Fügen Sie den Backoff-Verzögerungen eine kleine zufällige Menge „Jitter“ hinzu, um das „Thundering Herd“-Problem zu vermeiden, bei dem viele Clients gleichzeitig Wiederholungen versuchen.

Gründlich protokollieren

Protokollieren Sie die vollständige Fehlerantwort, einschließlich aller Standardnutzlasten mit Details, insbesondere der Anfrage-ID. Diese Informationen sind für die Fehlerbehebung und die Meldung von Problemen an den Google-Support erforderlich.

Nutzerfeedback geben

Geben Sie den Nutzern Ihrer Anwendung anhand der Codes und Nachrichten in den Standardnutzlasten mit Details klares und hilfreiches Feedback. Anstatt nur „Ein Fehler ist aufgetreten“ können Sie beispielsweise „Transaktions-ID fehlt“ oder „Die Konto-ID des Ziels wurde nicht gefunden“ angeben.

Wenn Sie diese Richtlinien befolgen, können Sie von der Data Manager API zurückgegebene Fehler effektiv diagnostizieren und beheben. So erhalten Sie stabilere und benutzerfreundlichere Anwendungen.

Zurück

Nutzerdaten verschlüsseln

Weiter

Best Practices