Trong API Google Ads, bạn có thể yêu cầu trả về lỗi không chặn trong các lệnh gọi API. Tính năng này, được gọi là “cảnh báo” (warnings), cho phép xử lý các lỗi không chặn một cách riêng biệt sau khi lệnh gọi API hoàn thành thành công.

Hiện tại, tính năng cảnh báo chỉ được hỗ trợ cho phương thức OfflineUserDataJobService.AddOfflineUserDataJobOperations khi tải dữ liệu ngoại tuyến liên quan đến giao dịch bán hàng tại cửa hàng thực tế.

Các trường hợp sử dụng cảnh báo

Thông báo thay đổi sắp tới:
Khi một tính năng chuẩn bị bị loại bỏ hoặc một quy tắc xác thực mới sắp được áp dụng, hệ thống sẽ cung cấp cảnh báo trong phản hồi để thông báo trước cho nhà phát triển. Điều này giúp nhà phát triển chuẩn bị các thay đổi cần thiết để tránh lỗi trong tương lai. Các cảnh báo này thường sẽ trở thành lỗi chặn trong các phiên bản API sau.
Xử lý lỗi không chặn:
Trong một số trường hợp, máy chủ có thể gặp lỗi không chặn (non-blocking errors), tức là các lỗi này không làm gián đoạn hoặc ngăn cản hoạt động chính của lệnh gọi API. Các lỗi không chặn này sẽ được trả về dưới dạng cảnh báo trong phản hồi.

Chi tiết kỹ thuật

Để kích hoạt tính năng cảnh báo cho một phương thức API, bạn cần cấu hình thuộc tính enable_warnings trong đối tượng yêu cầu tương ứng. Ví dụ, trong phương thức OfflineUserDataJobService.AddOfflineUserDataJobOperations, bạn có thể đặt trường enable_warnings trong đối tượng AddOfflineUserDataJobOperationsRequest để nhận cảnh báo.

Dịch vụ sẽ hoạt động đồng thời với các tham số khác như cờ validate_only (chỉ xác thực) và enable_partial_failure (cho phép lỗi cục bộ). Nếu lệnh gọi API hoàn thành thành công, các lỗi không chặn phát sinh trong quá trình thực thi sẽ được trả về trong trường warnings của phản hồi.

Cách sử dụng

Khi tải dữ liệu ngoại tuyến lên liên quan đến giao dịch bán hàng tại cửa hàng thực tế, bạn có thể cấu hình một thuộc tính không bắt buộc, chẳng hạn item_attribute. Nếu cung cấp giá trị không đúng định dạng cho thuộc tính này, lệnh gọi API vẫn sẽ hoàn thành thành công. Tuy nhiên, chi tiết về lỗi định dạng sai sẽ được trả về dưới dạng cảnh báo, giúp bạn xác định và khắc phục vấn đề mà không ảnh hưởng đến quá trình tải dữ liệu.

Tạo các thao tác và thực hiện lệnh gọi API

Tạo các thao tác thay đổi và thực hiện lệnh gọi API như bình thường.

// Gửi yêu cầu để thêm các thao tác vào offline user data job.

AddOfflineUserDataJobOperationsResponse response =

offlineUserDataJobServiceClient.addOfflineUserDataJobOperations(

AddOfflineUserDataJobOperationsRequest.newBuilder()

.setResourceName(offlineUserDataJobResourceName) // Đặt tên tài nguyên offline user data job.

.setEnablePartialFailure(true) // Bật chế độ xử lý lỗi một phần.

.setEnableWarnings(true) // Kích hoạt cảnh báo (tùy chọn).

.addAllOperations(userDataJobOperations) // Thêm danh sách các thao tác.

.build());

Kiểm tra và xử lý cảnh báo từ phản hồi API

Khi thao tác gửi thành công, bạn có thể kiểm tra và xử lý các cảnh báo trả về thông qua trường warnings. Trường này là một danh sách các chi tiết lỗi không chặn, mỗi chi tiết tương ứng với một thao tác đã gửi.

warnings là kiểu Status, chứa danh sách chi tiết lỗi.
Mỗi chi tiết tương ứng với mỗi thao tác đã gửi. Nó biểu thị một thực thể của GoogleAdsFailure.
GoogleAdsFailure chứa danh sách GoogleAdsError . Do đó, một thao tác đã gửi có thể chứa nhiều lỗi.
GoogleAdsError cho bạn biết thông báo lỗi, mã lỗi và tất cả các thông tin khác thông tin chi tiết có liên quan.

Hầu hết các thư viện của Google Ads API đều hỗ trợ các hàm tiện ích để trích xuất và hiển thị thông tin lỗi chi tiết mà không cần xử lý thủ công.

// Kiểm tra xem phản hồi có chứa cảnh báo hay không và xử lý chi tiết.

if (response.hasWarning()) {

// Chuyển đổi trường "Any" trong phản hồi về đối tượng GoogleAdsFailure.

GoogleAdsFailure warningsFailure =

ErrorUtils.getInstance().getGoogleAdsFailure(response.getWarning());

// Hiển thị thông tin về số lượng cảnh báo đã gặp phải.
System.out.println(
String.format(“Đã gặp %d cảnh báo.%n”, warningsFailure.getErrorsCount()));
}

Ví dụ về mã

Mỗi thư viện ứng dụng của Google Ads API cung cấp thư mục Remarketing, trong đó chứa các ví dụ mã minh họa cách sử dụng tính năng tải dữ liệu giao dịch ngoại tuyến (Offline User Data Job) và các thao tác remarketing khác.

Dưới đây là đoạn mã mẫu bằng Java, minh họa cách tải lên giao dịch bán hàng ngoại tuyến cho tính năng Store Sales Transactions.

// Copyright 2020 Google LLC

//

// Licensed under the Apache License, Version 2.0 (the "License");

// you may not use this file except in compliance with the License.

// You may obtain a copy of the License at

//

//     https://www.apache.org/licenses/LICENSE-2.0

//

// Unless required by applicable law or agreed to in writing, software

// distributed under the License is distributed on an "AS IS" BASIS,

// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.

// See the License for the specific language governing permissions and

// limitations under the License.

package com.google.ads.googleads.examples.remarketing;

import com.google.ads.googleads.lib.GoogleAdsClient;
import com.google.ads.googleads.v17.services.*;
import com.google.ads.googleads.v17.common.*;
import com.google.ads.googleads.v17.enums.*;
import com.google.ads.googleads.v17.resources.*;
import com.google.ads.googleads.v17.utils.ErrorUtils;

import java.io.IOException;
import java.util.List;

/**
* Uploads offline data for store sales transactions.
*
* <p>This example demonstrates the process of creating, populating, and running an offline user data job
* for store sales transactions. Note: this feature is only available for allowlisted accounts.
*/
public class UploadStoreSalesTransactions {

public static void main(String[] args) {
try {
GoogleAdsClient googleAdsClient = GoogleAdsClient.newBuilder().fromPropertiesFile().build();
// Call the method to execute the transaction upload process
executeStoreSalesTransactionUpload(googleAdsClient);
} catch (IOException e) {
System.err.printf(“Failed to create GoogleAdsClient. Exception: %s%n”, e);
}
}

/**
* Executes the process to upload store sales transactions.
*
* @param googleAdsClient the Google Ads API client instance.
*/
private static void executeStoreSalesTransactionUpload(GoogleAdsClient googleAdsClient) {
try (OfflineUserDataJobServiceClient offlineUserDataJobServiceClient =
googleAdsClient.getLatestVersion().createOfflineUserDataJobServiceClient()) {

String resourceName = createOfflineUserDataJob(offlineUserDataJobServiceClient, “customerId”);

List<OfflineUserDataJobOperation> operations = prepareTransactionData();
uploadOfflineUserData(offlineUserDataJobServiceClient, resourceName, operations);

// Optionally, check the job status
checkJobStatus(googleAdsClient, “customerId”, resourceName);

} catch (Exception e) {
System.err.printf(“An error occurred during the transaction upload process: %s%n”, e);
}
}

// Other supportive methods like createOfflineUserDataJob, prepareTransactionData, uploadOfflineUserData, and checkJobStatus are implemented similarly as in the original example.
}