Google sử dụng công nghệ AI để dịch nội dung sang ngôn ngữ bạn ưu tiên. Bản dịch bằng AI có thể có lỗi.

Tìm hiểu về lỗi API

Hướng dẫn này giải thích cách Data Manager API xử lý và thông báo lỗi. Việc hiểu rõ cấu trúc và ý nghĩa của lỗi API là rất quan trọng để xây dựng các ứng dụng mạnh mẽ có thể xử lý các vấn đề một cách linh hoạt, từ dữ liệu đầu vào không hợp lệ đến tình trạng dịch vụ tạm thời không hoạt động.

Data Manager API tuân theo mô hình lỗi API chuẩn của Google, dựa trên mã trạng thái gRPC. Mỗi phản hồi của API dẫn đến lỗi đều bao gồm một đối tượng Status có:

Mã lỗi dạng số.
Thông báo lỗi.
Thông tin chi tiết khác về lỗi (không bắt buộc).

Mã lỗi chuẩn

Data Manager API sử dụng một tập hợp mã lỗi chuẩn do gRPC và HTTP xác định. Các mã này cho biết thông tin tổng quan về loại lỗi. Bạn phải luôn kiểm tra mã này trước tiên để hiểu bản chất cơ bản của vấn đề.

Để biết thêm thông tin chi tiết về các mã này, hãy xem Hướng dẫn thiết kế API – Mã lỗi.

Mô hình thất bại nhanh

Data Manager API sử dụng mô hình lỗi nhanh. Nếu một yêu cầu có lỗi về cấu trúc hoặc nếu có bản ghi không vượt qua được quy trình xác thực cho một trường bắt buộc, thì toàn bộ yêu cầu sẽ không thành công và API sẽ không xử lý bất kỳ dữ liệu nào trong yêu cầu đó.

So sánh với mô hình lỗi một phần

Mô hình lỗi nhanh khác với mô hình lỗi một phần trong một số API khác của Google, chẳng hạn như Google Ads API và Campaign Manager 360 API. Trong mô hình lỗi một phần, yêu cầu sẽ thành công ngay cả khi một số bản ghi có lỗi và phản hồi chứa thông tin chi tiết về lỗi cho các bản ghi không thành công.

Mặc dù lỗi một phần có thể thuận tiện, nhưng nó mang lại rủi ro đáng kể vì mô hình lỗi một phần không chủ động cảnh báo cho bạn về lỗi – bạn phải kiểm tra rõ ràng lỗi trong mỗi phản hồi. Điều này có thể che giấu các vấn đề quan trọng vì yêu cầu thành công ngay cả khi API từ chối nhiều hoặc thậm chí tất cả bản ghi trong yêu cầu. Nếu một phần đáng kể các bản ghi trong một yêu cầu có lỗi nhưng bạn không kiểm tra phản hồi, thì bạn có thể hoàn toàn không biết về các vấn đề phổ biến với dữ liệu của mình và chỉ phát hiện ra những vấn đề đó sau nhiều ngày hoặc nhiều tuần khi kết quả tích luỹ không phù hợp với kỳ vọng của bạn.

Mô hình lỗi nhanh tránh được những vấn đề này bằng cách thông báo ngay cho bạn về các vấn đề liên quan đến dữ liệu hoặc quá trình tích hợp để bạn có thể thực hiện hành động thích hợp.

Kiểm tra lỗi không thành công nhanh bằng `validateOnly`

Hầu hết các yêu cầu nhập và yêu cầu gỡ bỏ đều hỗ trợ trường validateOnly. Khi bạn đặt validateOnly thành true, Data Manager API sẽ chạy các quy trình kiểm tra xác thực cơ bản giống như đối với một yêu cầu thông thường, nhưng không nhập hoặc xoá bất kỳ dữ liệu nào.

Nếu yêu cầu có lỗi, yêu cầu đó sẽ không thành công và trả về phản hồi lỗi giống như phản hồi bạn nhận được từ một yêu cầu thông thường.
Nếu yêu cầu vượt qua quy trình xác thực, thì yêu cầu đó sẽ thành công. Phản hồi bao gồm mọi fieldWarnings cho các trường tuỳ chọn, giống như một yêu cầu thông thường.

Sử dụng validateOnly để:

Kiểm thử một chế độ tích hợp mới hoặc đã cập nhật mà không ảnh hưởng đến dữ liệu thực tế của bạn.
Xác nhận rằng bản sửa lỗi đã giải quyết được lỗi trước khi bạn gửi lại yêu cầu.

Xử lý lỗi

Hãy làm theo các bước sau khi yêu cầu không thành công:

Kiểm tra mã lỗi để tìm loại lỗi.
- Nếu bạn sử dụng gRPC, mã lỗi sẽ nằm trong trường code của Status. Nếu bạn sử dụng thư viện ứng dụng, thì thư viện đó có thể gửi một loại ngoại lệ cụ thể tương ứng với mã lỗi. Ví dụ: thư viện ứng dụng cho Java sẽ gửi một com.google.api.gax.rpc.InvalidArgumentException nếu mã lỗi là INVALID_ARGUMENT.
- Nếu bạn sử dụng REST, mã lỗi sẽ nằm trong phản hồi lỗi tại error.status và trạng thái HTTP tương ứng sẽ nằm tại error.code.
Quan trọng: Data Manager API sử dụng mô hình lỗi nhanh. Nếu một yêu cầu không thành công, thì không có dữ liệu nào được xử lý. Hãy khắc phục lỗi rồi gửi lại toàn bộ yêu cầu.
Kiểm tra trọng tải chi tiết tiêu chuẩn để biết mã lỗi. Trọng tải chi tiết tiêu chuẩn là một tập hợp thông báo lỗi từ API của Google. Các lớp này cung cấp cho bạn thông tin chi tiết về lỗi theo cách có cấu trúc và nhất quán. Mỗi lỗi từ Data Manager API có thể có nhiều thông báo tải trọng chi tiết tiêu chuẩn. Thư viện ứng dụng Data Manager API có các phương thức trợ giúp để lấy thông tin chi tiết tiêu chuẩn từ một lỗi.

Bất kể mã lỗi là gì, bạn nên kiểm tra và ghi lại các tải trọng ErrorInfo, RequestInfo, Help và LocalizedMessage.
- ErrorInfo có thông tin có thể không có trong các tải trọng khác.
- RequestInfo có mã yêu cầu, mã này sẽ hữu ích nếu bạn cần liên hệ với nhóm hỗ trợ.
- Help và LocalizedMessage chứa các đường liên kết và thông tin khác để giúp bạn giải quyết lỗi.
Ngoài ra, tải trọng BadRequest còn hữu ích cho các lỗi INVALID_ARGUMENT vì tải trọng này cung cấp thông tin về những trường gây ra lỗi.

Cảnh báo khi phân tích

Data Manager API chấp nhận nhiều yêu cầu nhập dữ liệu nhất có thể. Nếu bạn cung cấp dữ liệu không bắt buộc, thì lỗi xác thực đối với các trường đó sẽ không khiến yêu cầu không thành công. Ví dụ: nếu một mặt hàng trong giỏ hàng thiếu mã sản phẩm của người bán, thì API sẽ xử lý phần còn lại của yêu cầu và trả về một cảnh báo.

Phản hồi nhập thành công (mã trạng thái HTTP 200) bao gồm các cảnh báo này trong danh sách fieldWarnings. Mỗi mục nhập là một đối tượng FieldWarning có các trường sau:

field

Vị trí của trường trong yêu cầu, theo cú pháp đường dẫn kiểu viết con rắn.

Nếu một đường dẫn trỏ đến một mục trong danh sách (trường repeated), thì chỉ mục của mục đó sẽ xuất hiện trong dấu ngoặc vuông ([...]) sau tên của danh sách.

Ví dụ: events.events[0].cart_data.items[0].merchant_product_id xác định một cảnh báo liên quan đến mục đầu tiên trong dữ liệu giỏ hàng của sự kiện đầu tiên trong yêu cầu.

description

Nội dung giải thích lý do giá trị được cung cấp gây ra cảnh báo.

reason

Giá trị enum WarningReason xác định loại cảnh báo.

Ví dụ về `FieldWarning`

Dưới đây là phản hồi mẫu cho một yêu cầu nhập thành công có chứa cảnh báo vì thiếu mã sản phẩm của người bán cho một trong các mặt hàng trong giỏ hàng.

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

Trọng tải chi tiết tiêu chuẩn

Sau đây là các tải trọng chi tiết tiêu chuẩn phổ biến nhất cho Data Manager API:

BadRequest
RequestInfo
ErrorInfo
Help và LocalizedMessage

`BadRequest`

Kiểm tra tải trọng BadRequest khi yêu cầu không thành công với INVALID_ARGUMENT (mã trạng thái HTTP 400).

Thông báo BadRequest cho biết yêu cầu có các trường có giá trị không hợp lệ hoặc thiếu giá trị cho một trường bắt buộc. Kiểm tra danh sách field_violations trong BadRequest để tìm những trường có lỗi. Mỗi mục nhập field_violations đều có thông tin giúp bạn khắc phục lỗi:

field

Vị trí của trường trong yêu cầu, theo cú pháp đường dẫn kiểu viết con rắn.

Ví dụ: destinations[0].operating_account.account_id là account_id trong operating_account của mục đầu tiên trong danh sách destinations.

description

Nội dung giải thích lý do giá trị đó gây ra lỗi.

reason

Enum ErrorReason, chẳng hạn như INVALID_HEX_ENCODING hoặc INVALID_CURRENCY_CODE.

Ví dụ về `BadRequest`

Dưới đây là phản hồi mẫu cho lỗi INVALID_ARGUMENT kèm theo thông báo BadRequest. field_violations cho thấy lỗi là accountId không phải là một số. Giá trị field destinations[0].login_account.account_id cho thấy accountId có trường vi phạm nằm trong login_account của mục đầu tiên trong danh sách destinations.

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

Sau đây là một phản hồi mẫu khác từ lỗi INVALID_ARGUMENT có thông báo BadRequest. Trong trường hợp này, danh sách field_violations cho thấy hai lỗi:

event đầu tiên có giá trị không được mã hoá theo hệ thập lục phân trên giá trị nhận dạng người dùng thứ hai của sự kiện.
event thứ hai có một giá trị không được mã hoá theo hệ thập lục phân trên giá trị nhận dạng người dùng thứ ba của sự kiện.

{
  "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`

Kiểm tra tải trọng RequestInfo bất cứ khi nào yêu cầu không thành công. RequestInfo chứa request_id giúp xác định duy nhất yêu cầu API của bạn.

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

Khi ghi nhật ký lỗi hoặc liên hệ với nhóm hỗ trợ, hãy nhớ cung cấp mã yêu cầu để giúp chẩn đoán vấn đề.

`ErrorInfo`

Kiểm tra thông báo ErrorInfo để truy xuất thông tin bổ sung có thể không được ghi lại trong các tải trọng chi tiết tiêu chuẩn khác. Nội dung tải ErrorInfo chứa bản đồ metadata có thông tin về lỗi.

Ví dụ: dưới đây là ErrorInfo cho lỗi PERMISSION_DENIED do sử dụng thông tin đăng nhập cho một dự án trên đám mây của Google Cloud chưa bật Data Manager API. ErrorInfo cung cấp thêm thông tin về lỗi, chẳng hạn như:

Dự án liên kết với yêu cầu, trong metadata.consumer.
Tên của dịch vụ, trong metadata.serviceTitle.
URL nơi bạn có thể bật dịch vụ, trong 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"
        }
      },
      ...
    ]
  }
}

Lỗi về hạn mức và giới hạn số lượng yêu cầu

Khi một yêu cầu vượt quá giới hạn của dự án, API sẽ trả về lỗi RESOURCE_EXHAUSTED (mã trạng thái HTTP 429). Trọng tải ErrorInfo cung cấp thông tin chi tiết về giới hạn đã vượt quá trong bản đồ metadata:

consumer: Dự án trên Google Cloud liên kết với yêu cầu, được định dạng là projects/PROJECT_NUMBER.
quota_limit: Tên của hạn mức đã vượt quá, chẳng hạn như IngestionMutateRequestsPerMinutePerProject hoặc IngestionMutateRequestsPerDayPerProject. Bạn có thể sử dụng giá trị này để xác định xem ứng dụng có vượt quá giới hạn mỗi phút hay giới hạn hằng ngày hay không. Để xem danh sách đầy đủ các tên giới hạn, hãy xem phần Giới hạn của dự án.
quota_location: Vị trí áp dụng hạn mức. Đối với Data Manager API, giá trị này luôn là global.
quota_metric: Chỉ số liên quan đến hạn mức, chẳng hạn như datamanager.googleapis.com/ingestion_mutate_requests.
service: Tên của dịch vụ, datamanager.googleapis.com.

Sau đây là ví dụ về phản hồi lỗi RESOURCE_EXHAUSTED khi một yêu cầu vượt quá giới hạn mỗi phút đối với yêu cầu thay đổi tài nguyên nhập:

{
  "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` và `LocalizedMessage`

Kiểm tra tải trọng Help và LocalizedMessage để lấy đường liên kết đến tài liệu và thông báo lỗi đã bản địa hoá, giúp bạn hiểu và khắc phục lỗi.

Ví dụ: dưới đây là Help và LocalizedMessage cho lỗi PERMISSION_DENIED do sử dụng thông tin xác thực cho một dự án trên Google Cloud mà API Trình quản lý dữ liệu chưa được bật. Trọng tải Help cho thấy URL nơi bạn có thể bật dịch vụ và LocalizedMessage có nội dung mô tả lỗi.

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

Thông tin chi tiết về lỗi truy cập

Nếu bạn đang sử dụng một trong các thư viện ứng dụng, hãy sử dụng các phương thức trợ giúp để lấy tải trọng chi tiết chuẩn.

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

Xử lý lỗi kích thước tiêu đề cho gRPC

Khi một số lượng lớn bản ghi trong yêu cầu truyền dẫn hoặc yêu cầu gỡ bỏ không xác thực được, Data Manager API sẽ trả về tất cả lỗi trong tải trọng BadRequest của phản hồi.

Trong gRPC, dịch vụ sẽ trả về các thông tin chi tiết về lỗi này trong tiêu đề phản hồi HTTP/2 (siêu dữ liệu). Theo mặc định, các thư viện ứng dụng gRPC giới hạn tiêu đề đến ở một kích thước tối đa (thường là 8 – 10 KB). Nếu thông tin chi tiết về lỗi vượt quá giới hạn này, thì quá trình truyền tải HTTP/2 phía máy khách sẽ không thành công trước khi phân tích cú pháp phản hồi lỗi, từ đó gửi một ngoại lệ như:

Http2Exception: Header size exceeded max allowed size (10240)

Vì ứng dụng không thể xử lý tiêu đề phản hồi, nên ứng dụng sẽ huỷ luồng (xuất hiện dưới dạng trạng thái HTTP 499 Client Closed Request trong nhật ký phía máy chủ) và ứng dụng của bạn không thể truy cập vào thông tin chi tiết về lỗi BadRequest.

Để giải quyết vấn đề này và kiểm tra danh sách đầy đủ các lỗi, hãy định cấu hình ứng dụng gRPC của bạn với kích thước siêu dữ liệu đến tối đa tăng lên (chẳng hạn như 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();IngestAudienceMembers.cs

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)) {
  // ...
}IngestAudienceMembers.java

Nút

// 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,
});ingest_audience_members.ts

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,
            ],
        ],
    ],
]);ingest_audience_members.php

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)
)ingest_audience_members.py

Các phương pháp hay nhất để xử lý lỗi

Để xây dựng ứng dụng có khả năng thích ứng, hãy triển khai các phương pháp hay nhất sau đây.

Xác thực trước khi gửi

Khi bạn xây dựng hoặc thay đổi một quy trình tích hợp, hãy gửi yêu cầu có validateOnly được đặt thành true để phát hiện lỗi nhanh trước khi bạn nhập dữ liệu.

Kiểm tra thông tin chi tiết về lỗi

Luôn tìm một trong các tải trọng chi tiết tiêu chuẩn, chẳng hạn như BadRequest. Mỗi tải trọng chi tiết tiêu chuẩn đều chứa thông tin giúp bạn hiểu được nguyên nhân gây ra lỗi.

Phân biệt lỗi máy khách với lỗi phía máy chủ

Xác định xem lỗi là do vấn đề với quá trình triển khai (máy khách) hay vấn đề với API (máy chủ).

Lỗi ứng dụng: Các mã như INVALID_ARGUMENT, NOT_FOUND, PERMISSION_DENIED, FAILED_PRECONDITION, UNAUTHENTICATED. Những lỗi này yêu cầu bạn phải thay đổi yêu cầu hoặc trạng thái/thông tin xác thực của ứng dụng. Đừng thử gửi lại yêu cầu nếu chưa giải quyết vấn đề.
Lỗi phía máy chủ: Các mã như UNAVAILABLE, INTERNAL, DEADLINE_EXCEEDED, UNKNOWN. Những lỗi này cho thấy dịch vụ API đang gặp sự cố tạm thời.

Triển khai chiến lược thử lại

Xác định xem có thể thử lại lỗi hay không và sử dụng chiến lược thử lại.

Chỉ thử lại đối với các lỗi tạm thời của máy chủ (chẳng hạn như UNAVAILABLE, DEADLINE_EXCEEDED, INTERNAL, UNKNOWN và ABORTED) và giới hạn số lượng yêu cầu mỗi phút (RESOURCE_EXHAUSTED có RATE_LIMIT_EXCEEDED).
Để biết giới hạn số lượng yêu cầu, hãy kiểm tra quota_limit trong ErrorInfo:
- Nếu giới hạn là mỗi phút (chẳng hạn như IngestionMutateRequestsPerMinutePerProject), hãy tạm dừng các yêu cầu và thử lại bằng thuật toán thời gian đợi luỹ thừa có độ gián đoạn.
- Nếu giới hạn là hằng ngày (chẳng hạn như IngestionMutateRequestsPerDayPerProject), đừng thử lại ngay. Tạm dừng xử lý cho đến khi hạn mức hằng ngày được đặt lại vào lúc nửa đêm theo Giờ Thái Bình Dương.
Sử dụng thuật toán đợi luỹ tuyến để chờ khoảng thời gian tăng dần giữa các lần thử lại. Điều này giúp tránh làm quá tải một dịch vụ vốn đã bị quá tải. Ví dụ: đợi 1 giây, sau đó là 2 giây, rồi 4 giây, tiếp tục cho đến khi đạt số lần thử lại tối đa hoặc tổng thời gian chờ.
Thêm một lượng nhỏ "jitter" ngẫu nhiên vào độ trễ thời gian đợi để ngăn chặn vấn đề "thundering herd" (bầy đàn sấm sét) khi nhiều ứng dụng khách thử lại cùng một lúc.

Ghi nhật ký kỹ lưỡng

Ghi lại toàn bộ phản hồi lỗi, bao gồm tất cả tải trọng chi tiết tiêu chuẩn, đặc biệt là mã yêu cầu. Thông tin này rất cần thiết cho việc gỡ lỗi và báo cáo vấn đề cho Nhóm hỗ trợ Google nếu cần.

Cung cấp ý kiến phản hồi của người dùng

Dựa trên các mã và thông báo trong tải trọng chi tiết tiêu chuẩn, hãy cung cấp ý kiến phản hồi rõ ràng và hữu ích cho người dùng ứng dụng của bạn. Ví dụ: thay vì chỉ nói "Đã xảy ra lỗi", bạn có thể nói "Thiếu mã giao dịch" hoặc "Không tìm thấy mã tài khoản của đích đến".

Bằng cách làm theo các nguyên tắc này, bạn có thể chẩn đoán và xử lý hiệu quả các lỗi do Data Manager API trả về, nhờ đó giúp ứng dụng hoạt động ổn định và thân thiện hơn với người dùng.

Mã hoá dữ liệu người dùng

Tiếp

Các phương pháp hay nhất

Tìm hiểu về lỗi API Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Mã lỗi chuẩn

Mô hình thất bại nhanh

So sánh với mô hình lỗi một phần

Kiểm tra lỗi không thành công nhanh bằng validateOnly

Xử lý lỗi

Cảnh báo khi phân tích

Ví dụ về FieldWarning

Trọng tải chi tiết tiêu chuẩn

BadRequest

Ví dụ về BadRequest

RequestInfo

ErrorInfo

Lỗi về hạn mức và giới hạn số lượng yêu cầu

Help và LocalizedMessage

Thông tin chi tiết về lỗi truy cập

.NET

Java

Xử lý lỗi kích thước tiêu đề cho gRPC

.NET

Java

Nút

PHP

Python

Các phương pháp hay nhất để xử lý lỗi

Tìm hiểu về lỗi API

Kiểm tra lỗi không thành công nhanh bằng `validateOnly`

Ví dụ về `FieldWarning`

`BadRequest`

Ví dụ về `BadRequest`

`RequestInfo`

`ErrorInfo`

`Help` và `LocalizedMessage`