API-Fehler verstehen

In diesem Leitfaden wird erläutert, wie die Data Manager API Fehler verarbeitet und kommuniziert. Die Struktur und Bedeutung von API-Fehlern zu verstehen, ist entscheidend für die Entwicklung robuster Anwendungen, die Probleme wie ungültige Eingaben oder vorübergehende Dienstausfälle ordnungsgemäß verarbeiten können.

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

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

Kanonische Fehlercodes

Die Data Manager API verwendet eine Reihe von kanonischen 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 Natur des Problems zu verstehen.

Weitere Informationen zu diesen Codes finden Sie im API-Designleitfaden – Fehlercodes.

Fast-Fail-Modell

Die Data Manager API verwendet ein Fast-Fail-Modell. Wenn eine Anfrage strukturelle Fehler enthält oder ein Eintrag die Validierung für ein Pflichtfeld nicht besteht, schlägt die gesamte Anfrage fehl und die API verarbeitet keine der Daten in dieser Anfrage.

Vergleich mit dem Modell für Teilausfälle

Das Fast-Fail-Modell unterscheidet sich vom Modell für Teilausfälle in einigen anderen Google APIs, z. B. der Google Ads API und der Campaign Manager 360 API. Im Modell für Teilausfälle ist eine Anfrage auch dann erfolgreich, wenn einige Einträge Fehler enthalten. Die Antwort enthält dann Fehlerdetails für die fehlgeschlagenen Einträge.

Ein teilweiser Fehler kann zwar praktisch sein, birgt aber erhebliche Risiken, da das Modell für teilweise Fehler Sie nicht proaktiv auf Fehler hinweist. Sie müssen jede Antwort explizit auf Fehler prüfen. Dies kann wichtige Probleme verdecken, 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 Ihnen die weit verbreiteten Probleme mit Ihren Daten möglicherweise gar nicht bewusst. Sie entdecken diese Probleme dann erst Tage oder Wochen später, wenn die kumulierten Ergebnisse nicht Ihren Erwartungen entsprechen.

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

Mit validateOnly auf Fast-Fail-Fehler prüfen

Die meisten Aufnahme- und Entfernungsanfragen unterstützen ein validateOnly-Feld. Wenn Sie validateOnly auf true setzen, führt die Data Manager API dieselben grundlegenden Validierungsprüfungen wie bei einer regulären Anfrage durch, nimmt aber keine Daten auf und entfernt auch keine.

  • Wenn die Anfrage Fehler enthält, schlägt sie mit derselben Fehlerantwort fehl, die Sie bei einer regulären Anfrage erhalten würden.
  • Wenn die Anfrage die Validierung besteht, ist sie erfolgreich. Die Antwort enthält wie eine reguläre Anfrage alle fieldWarnings für optionale Felder.

Funktionen von validateOnly:

  • Sie können eine neue oder aktualisierte Integration testen, ohne dass sich dies auf Ihre Live-Daten auswirkt.
  • Prüfen Sie, ob ein Fehler durch eine Korrektur behoben wurde, bevor Sie die Anfrage noch einmal senden.

Fehler verarbeiten

Gehen Sie so vor, wenn eine Anfrage fehlschlägt:

  1. Prüfen Sie den Fehlercode, um den Fehlertyp zu ermitteln.

    • Wenn Sie gRPC verwenden, befindet sich der Fehlercode im Feld code des Status. Wenn Sie eine Clientbibliothek verwenden, wird möglicherweise ein bestimmter Ausnahmetyp ausgelöst, der dem Fehlercode entspricht. Die Clientbibliothek für Java gibt beispielsweise eine com.google.api.gax.rpc.InvalidArgumentException aus, wenn der Fehlercode INVALID_ARGUMENT lautet.
    • Wenn Sie REST verwenden, befindet sich der Fehlercode in der Fehlerantwort unter error.status und der entsprechende HTTP-Status unter error.code.

  2. Suchen Sie nach der Standard-Detailnutzlast für den Fehlercode. Die Standard-Detailnutzlasten sind eine Reihe von Nachrichten für Fehler von Google APIs. Sie enthalten Fehlerdetails in strukturierter und einheitlicher Form. Jeder Fehler der Data Manager API kann mehrere Standard-Detailnutzlastnachrichten enthalten. Die Data Manager API-Clientbibliotheken bieten Hilfsmethoden, um die Standard-Detailnutzlasten aus einem Fehler abzurufen.

    Unabhängig vom Fehlercode empfehlen wir, die Nutzlasten ErrorInfo, RequestInfo, Help und LocalizedMessage zu prüfen und zu protokollieren.

    • ErrorInfo enthält Informationen, die in anderen Nutzlasten möglicherweise nicht 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 darüber liefert, welche Felder den Fehler verursacht haben.

Aufnahmewarnungen

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

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

field

Die Position des Felds in der Anfrage in der Pfadsyntax „snake_case“.

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 kennzeichnet beispielsweise eine Warnung im Zusammenhang mit dem ersten Artikel in den Warenkorbdaten des ersten Ereignisses in der Anfrage.

description

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

reason

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

Beispiel mit FieldWarning

Hier ist eine Beispielantwort für eine erfolgreiche Aufnahme-Anfrage, die eine Warnung enthält, weil für einen der Artikel im Einkaufswagen eine Händler-Produkt-ID fehlte.

{
  "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"
    }
  ]
}

Standard-Detailnutzlasten

Die gängigsten Standard-Detail-Nutzlasten für die Data Manager API sind:

BadRequest

Prüfen Sie, ob die Nutzlast BadRequest vorhanden ist, wenn eine Anfrage mit INVALID_ARGUMENT (HTTP-Statuscode 400) fehlschlägt.

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

field

Die Position des Felds in der Anfrage in der Pfadsyntax „snake_case“.

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 der account_id im operating_account des ersten Elements in der Liste destinations.

description

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

reason

Das ErrorReason-Enum, z. B. INVALID_HEX_ENCODING oder INVALID_CURRENCY_CODE.

Beispiele für BadRequest

Hier sehen Sie ein Beispiel für eine Antwort auf einen INVALID_ARGUMENT-Fehler mit einer BadRequest-Nachricht. Die field_violations zeigen, dass der Fehler ein accountId ist, das keine Zahl ist. Der field-Wert destinations[0].login_account.account_id zeigt, dass sich die accountId mit einem Feldverstoß im login_account des ersten Elements in der destinations-Liste 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 auf einen INVALID_ARGUMENT-Fehler mit einer BadRequest-Nachricht. In diesem Fall werden in der Liste field_violations zwei Fehler angezeigt:

  1. Die erste event hat einen Wert, der nicht hexadezimal codiert ist, für die zweite Nutzer-ID des Ereignisses.

  2. Die 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

Prüfen Sie bei jeder fehlgeschlagenen Anfrage, ob die Nutzlast RequestInfo vorhanden ist. Ein 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 den Support kontaktieren, geben Sie 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 Standarddetail-Nutzlasten enthalten sind. Die ErrorInfo-Nutzlast enthält eine metadata-Zuordnung mit Informationen zum Fehler.

Hier ist beispielsweise der 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. 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"
        }
      },
      ...
    ]
  }
}

Kontingent- und Ratenbegrenzungsfehler

Wenn eine Anfrage ein Projektlimit überschreitet, gibt die API den Fehler RESOURCE_EXHAUSTED (HTTP-Statuscode 429) zurück. Die Nutzlast ErrorInfo enthält in der Zuordnung metadata Details dazu, welches Limit überschritten wurde:

consumer
Das mit der Anfrage verknüpfte Google Cloud-Projekt, formatiert als projects/PROJECT_NUMBER.
quota_limit
Der Name des überschrittenen Kontingentlimits, z. B. IngestionMutateRequestsPerMinutePerProject oder IngestionMutateRequestsPerDayPerProject. Anhand dieses Werts können Sie feststellen, ob die Anwendung ein Minuten- oder Tageslimit überschritten hat. Eine vollständige Liste der Limitnamen finden Sie unter Projektlimits.
quota_location
Der Standort, an dem das Kontingent erzwungen wird. Für die Data Manager API ist dies immer global.
quota_metric
Der mit dem Limit verknüpfte Messwert, z. B. datamanager.googleapis.com/ingestion_mutate_requests.
service
Der Name des Dienstes, datamanager.googleapis.com.

Hier ist ein Beispiel für eine RESOURCE_EXHAUSTED-Fehlerantwort, wenn eine Anfrage das Limit pro Minute für Mutationsanfragen zur Aufnahme überschreitet:

{
  "error": {
    "code": 429,
    "message": "Quota exceeded for quota metric 'Ingestion mutate requests' and limit 'Ingestion mutate requests per minute' of service 'datamanager.googleapis.com' for consumer 'project_number:PROJECT_NUMBER'.",
    "status": "RESOURCE_EXHAUSTED",
    "details": [
      {
        "@type": "type.googleapis.com/google.rpc.ErrorInfo",
        "reason": "RATE_LIMIT_EXCEEDED",
        "domain": "googleapis.com",
        "metadata": {
          "consumer": "projects/PROJECT_NUMBER",
          "quota_limit": "IngestionMutateRequestsPerMinutePerProject",
          "quota_location": "global",
          "quota_metric": "datamanager.googleapis.com/ingestion_mutate_requests",
          "service": "datamanager.googleapis.com"
        }
      }
    ]
  }
}

Help und LocalizedMessage

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

Hier sind beispielsweise 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 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, rufen Sie die Standarddetail-Nutzlasten mit den Hilfsmethoden ab.

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

            // If handling a rate limit error, check the exceeded quota limit:
            if (errorInfo.Reason == "RATE_LIMIT_EXCEEDED" &&
                errorInfo.Metadata.TryGetValue("quota_limit", out string quotaLimit))
            {
                // Inspect quotaLimit to determine whether it is a per-minute
                // or daily limit (for example,
                // IngestionMutateRequestsPerMinutePerProject).
            }

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

  // If handling a rate limit error, check the exceeded quota limit:
  if (errorInfo != null && "RATE_LIMIT_EXCEEDED".equals(errorInfo.getReason())) {
    String quotaLimit = errorInfo.getMetadataMap().get("quota_limit");
    // Inspect quotaLimit to determine whether it is a per-minute
    // or daily limit (for example,
    // IngestionMutateRequestsPerMinutePerProject).
  }

  // 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 = apiException.getErrorDetails().getRequestInfo();
  if (requestInfo != null) {
    String requestId = requestInfo.getRequestId();
    // Log the requestId...
  }
  ...
}

Fehler bei der Headergröße für gRPC behandeln

Wenn eine große Anzahl von Datensätzen in einer Anfrage zur Datenaufnahme oder einem Antrag auf Entfernung die Validierung nicht besteht, gibt die Data Manager API alle Fehler in der Nutzlast BadRequest der Antwort zurück.

In gRPC gibt der Dienst diese Fehlerdetails in den HTTP/2-Antwortheadern (Metadaten) zurück. Standardmäßig begrenzen gRPC-Clientbibliotheken eingehende Header auf eine maximale Größe (normalerweise 8–10 KB). Wenn die Fehlerdetails dieses Limit überschreiten, schlägt der clientseitige HTTP/2-Transport fehl, bevor die Fehlerantwort geparst wird. Es wird eine Ausnahme wie die folgende ausgegeben:

Http2Exception: Header size exceeded max allowed size (10240)

Da der Client die Antwortheader nicht verarbeiten kann, bricht er den Stream ab (was in serverseitigen Logs als HTTP-Status 499 Client Closed Request angezeigt wird) und Ihre Anwendung kann nicht auf die BadRequest-Fehlerdetails zugreifen.

Um dieses Problem zu beheben und die vollständige Liste der Fehler zu prüfen, konfigurieren Sie Ihren gRPC-Client mit einer höheren maximalen Größe für eingehende Metadaten (z. B. 16 MB):

.NET

// Creates a client for the ingestion service. Increases the maximum metadata size to
// 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain large error
// details.
IngestionServiceClient ingestionServiceClient = new IngestionServiceClientBuilder
{
    GrpcChannelOptions = GrpcChannelOptions.Empty.WithCustomOption(
        "grpc.max_metadata_size",
        16 * 1024 * 1024
    ),
}.Build();

Java

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
InstantiatingGrpcChannelProvider provider =
    IngestionServiceSettings.defaultGrpcTransportProviderBuilder()
        .setMaxInboundMetadataSize(16 * 1024 * 1024)
        .build();
IngestionServiceSettings settings =
    IngestionServiceSettings.newBuilder().setTransportChannelProvider(provider).build();
try (IngestionServiceClient ingestionServiceClient = IngestionServiceClient.create(settings)) {
  // ...
}

Node

// Creates a client for the ingestion service. Increases the maximum metadata
// size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses contain
// large error details.
const client = new IngestionServiceClient({
  'grpc.max_metadata_size': 16 * 1024 * 1024,
});

PHP

// Creates a client for the ingestion service. Increases the maximum metadata size to 16MB to
// prevent RESOURCE_EXHAUSTED errors when responses contain large error details.
$client = new IngestionServiceClient([
    'transportConfig' => [
        'grpc' => [
            'stubOpts' => [
                'grpc.max_metadata_size' => 16 * 1024 * 1024,
            ],
        ],
    ],
]);

Python

# Creates a client for the ingestion service. Increases the maximum
# metadata size to 16MB to prevent RESOURCE_EXHAUSTED errors when responses
# contain large error details.
channel = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport.create_channel(
    options=[("grpc.max_metadata_size", 16 * 1024 * 1024)]
)
transport = datamanager_v1.services.ingestion_service.transports.IngestionServiceGrpcTransport(
    channel=channel
)
client: datamanager_v1.IngestionServiceClient = (
    datamanager_v1.IngestionServiceClient(transport=transport)
)

Best Practices für die Fehlerbehandlung

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

Vor dem Senden validieren
Wenn Sie eine Integration erstellen oder ändern, senden Sie Anfragen, bei denen validateOnly auf true gesetzt ist, um Fast-Fail-Fehler zu erkennen, bevor Sie Daten aufnehmen.
Fehlerdetails prüfen
Suchen Sie immer nach einer der Standard-Detailnutzlasten wie BadRequest. Jede Standarddetailnutzlast 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 durch ein Problem 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 weisen auf ein vorübergehendes Problem mit dem API-Dienst hin.
Wiederholungsstrategie implementieren

Prüfen Sie, ob der Fehler wiederholt werden kann, und verwenden Sie eine Wiederholungsstrategie.

  • Wiederholen Sie den Vorgang nur bei vorübergehenden Serverfehlern (z. B. UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN und ABORTED) und bei Ratenbegrenzungen pro Minute (RESOURCE_EXHAUSTED mit RATE_LIMIT_EXCEEDED).

  • Informationen zu Ratenbegrenzungen finden Sie unter quota_limit in ErrorInfo:

    • Wenn das Limit pro Minute gilt (z. B. IngestionMutateRequestsPerMinutePerProject), pausieren Sie die Anfragen und versuchen Sie es mit exponentiellem Backoff mit Jitter noch einmal.

    • Wenn das Limit täglich ist (z. B. IngestionMutateRequestsPerDayPerProject), versuchen Sie es nicht sofort noch einmal. Pausieren Sie die Verarbeitung, bis das Tageskontingent um Mitternacht (UTC -7/-8) zurückgesetzt wird.

  • Verwenden Sie einen exponentiellen Backoff-Algorithmus, um zwischen den Wiederholungsversuchen immer länger zu warten. So wird vermieden, dass ein bereits überlasteter Dienst überfordert wird. Warten Sie beispielsweise 1 Sekunde, dann 2 Sekunden, dann 4 Sekunden, bis zu einer maximalen Anzahl von Wiederholungsversuchen oder einer maximalen Gesamtwartezeit.

  • Fügen Sie den Backoff-Verzögerungen einen kleinen zufälligen „Jitter“ hinzu, um das „Thundering-Herd-Problem“ zu vermeiden, bei dem viele Clients gleichzeitig einen Wiederholungsversuch starten.

Detailliert protokollieren

Protokollieren Sie die vollständige Fehlerantwort, einschließlich aller Standarddetailnutzlasten, 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 Standarddetail-Nutzlasten 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 nutzerfreundlichere Anwendungen.

Zurück
Nutzerdaten verschlüsseln
Weiter
Best Practices