Thay đổi

Tập lệnh Google Ads hỗ trợ các biến đổi chung có trong API Google Ads. Hầu hết các thao tác có thể thực hiện từ GoogleAdsService.mutate cũng có thể được thực hiện trong tập lệnh Google Ads, bao gồm cả việc tạo và quản lý chiến dịch.

Vì tính năng này cho phép truy cập vào một phần lớn API Google Ads, nên bạn cần có kiến thức cơ bản về các quy ước của API Google Ads để sử dụng tính năng này. Bạn có thể bỏ qua nhiều khía cạnh, chẳng hạn như mã thông báo nhà phát triển và quyền uỷ quyền, vì các khía cạnh đó được xử lý cho bạn bằng tập lệnh Google Ads, nhưng bạn phải tạo một yêu cầu thay đổi hợp lệ.

Dưới đây là một số tài nguyên cơ bản về giao diện REST của API Google Ads mà bạn nên làm quen trước khi tiếp tục với hướng dẫn này:

• Thiết kế giao diện REST
• Tên tài nguyên
• Ánh xạ JSON
• Thay đổi

Ví dụ cơ bản

Để minh hoạ chức năng này, hãy xem xét ví dụ cơ bản sau đây về cách tạo ngân sách chiến dịch:

const budgetResult = AdsApp.mutate({
    campaignBudgetOperation: {
      create: {
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });

Lệnh gọi đến AdsApp.mutate sẽ lấy một đối tượng JSON đại diện cho một MutateOperation. Trong đối tượng này, bạn chỉ định loại thao tác mà bạn đang thực hiện – trong trường hợp này là campaignBudgetOperation. Sau đó, bạn chỉ định create, remove hoặc cả update và updateMask. Các trường cụ thể trong create và update phụ thuộc vào loại tài nguyên cụ thể mà bạn đang hoạt động.

Tạo một toán tử

Bạn có thể sử dụng một số chiến lược để tạo một phép toán hợp lệ. Tiếp tục với ví dụ về ngân sách chiến dịch, bạn có thể tra cứu tài liệu tham khảo REST về ngân sách chiến dịch để xem danh sách tất cả các trường hợp hợp lệ, sau đó điền vào các trường thích hợp hoặc viết mã JavaScript tuỳ chỉnh trong tập lệnh để tạo một đối tượng thích hợp.

Ngoài ra, bạn có thể thử tạo một thao tác một cách linh động bằng cách sử dụng tính năng "Thử tính năng này" cho ngân sách chiến dịch. Tính năng này cho phép bạn tạo một nội dung yêu cầu một cách linh động bằng cách chọn những trường mà bạn muốn thêm. Sau đó, bạn có thể trích xuất nội dung của phép toán từ kết quả được tạo và thêm nội dung đó vào lệnh gọi mutate sau khi chỉ định loại phép toán.

Loại toán tử

Tạo

Chỉ định create trong thao tác của bạn, truyền vào một đối tượng đại diện cho tài nguyên mà bạn muốn tạo.

Hãy xem ví dụ ở trên về toán tử create.

Xóa

Chỉ định remove trong thao tác của bạn, truyền vào tên tài nguyên của tài nguyên bạn muốn xoá, ví dụ:

AdsApp.mutate({
    adGroupOperation: {
        remove: "customers/[CUSTOMER_ID]/adGroups/[AD_GROUP_ID]"
    }
});

Nếu không biết tên tài nguyên của một thực thể, bạn có thể tìm nạp tài nguyên đó bằng cách sử dụng yêu cầu Adsapp.search.

Cập nhật

Chỉ định update trong thao tác của bạn, truyền vào một đối tượng có tên tài nguyên được chỉ định để hệ thống có thể xác định đối tượng bạn muốn cập nhật. Ngoài ra, hãy điền vào mọi trường mà bạn muốn cập nhật giá trị và chỉ định updateMask cho biết chính xác những trường mà bạn dự định thay đổi trong yêu cầu này. Đừng đưa tên tài nguyên vào mặt nạ cập nhật.

Ví dụ về thao tác update:

const campaignResult = AdsApp.mutate({
    campaignOperation: {
        update: {
            resourceName: "customers/[CUSTOMER_ID]/campaigns/[CAMPAIGN_ID]",
            status: "PAUSED",
            name: "[Paused] My campaign"
        },
        updateMask: "name,status"
    }
});

Xử lý kết quả

Bất kể loại thao tác là gì, giá trị trả về đều là MutateResult. Bạn có thể sử dụng tên tài nguyên được trả về để truy vấn trạng thái hiện tại của tài nguyên sau khi thay đổi và kiểm tra xem thao tác có thành công hay không hoặc lỗi nào xảy ra (nếu có).

Sau đây là ví dụ minh hoạ quy trình cơ bản để kiểm tra kết quả và in một số thông tin vào nhật ký:

const result = AdsApp.mutate( ... );
if (result.isSuccessful()) {
    console.log(`Resource ${result.getResourceName()} successfully mutated.`);
} else {
    console.log("Errors encountered:");
    for (const error of result.getErrorMessages()) {
        console.log(error);
    }
}

Nhiều thao tác

Tập lệnh Google Ads cũng hỗ trợ việc thay đổi nhiều thao tác trong một yêu cầu bằng phương thức AdsApp.mutateAll. Bạn có thể tạo các thực thể phụ thuộc lẫn nhau, chẳng hạn như một hệ thống phân cấp chiến dịch đầy đủ trong một yêu cầu. Bạn có thể tuỳ ý tạo toàn bộ tập hợp thao tác ở dạng nguyên tử, vì vậy, nếu có bất kỳ thao tác nào không thành công thì sẽ không có thao tác nào được thực hiện.

Giá trị trả về là một mảng các đối tượng MutateResult, mỗi đối tượng cho một phép toán mà bạn cung cấp và theo thứ tự giống như các phép toán ban đầu.

Tính năng này hoạt động giống như tính năng API Google Ads, vì vậy, hãy tham khảo hướng dẫn Các phương pháp hay nhất về API Google Ads để biết nội dung giải thích đầy đủ về mã nhận dạng tạm thời và các vấn đề cần cân nhắc khác; lưu ý rằng hướng dẫn này sử dụng snake_case để biểu thị tên trường, trong khi tài liệu về tập lệnh Google Ads sử dụng lowerCamelCase. Cả hai trường hợp này đều được chấp nhận trong tập lệnh Google Ads, vì vậy, bạn có thể sao chép mã trực tiếp từ hướng dẫn đó.

Để thực hiện nhiều thao tác trong một yêu cầu, hãy thu thập tất cả thao tác vào một mảng, sau đó gọi AdsApp.mutateAll. Lệnh gọi mutateAll lấy mảng các thao tác làm đối số đầu tiên và đối số thứ hai không bắt buộc của các tuỳ chọn, bao gồm:

• apiVersion: Bạn có thể chỉ định một phiên bản API tuỳ chỉnh, chẳng hạn như V18, nếu muốn sử dụng một phiên bản không phải là phiên bản mặc định của tập lệnh. Bạn có thể sử dụng bất kỳ phiên bản nào được phát hành công khai tại thời điểm đó.
• partialFailure: Trường này được mặc định là true. Nếu bạn đặt thành true, thì thao tác hợp lệ sẽ được thực hiện và thao tác không thành công sẽ trả về lỗi. Nếu bạn đặt thành false, thì nếu bất kỳ thao tác nào không thành công, thì hệ thống sẽ không thực hiện thao tác nào, giúp nhóm thao tác này trở nên nguyên tử một cách hiệu quả.

Sau đây là ví dụ về nhiều thao tác tạo ngân sách chiến dịch, chiến dịch và nhóm quảng cáo trong một yêu cầu nguyên tử.

const operations = [];
const customerId = 'INSERT_CUSTOMER_ID_HERE';
const budgetId = `customers/${customerId}/campaignBudgets/-1`;
const campaignId = `customers/${customerId}/campaigns/-2`;
operations.push({
    campaignBudgetOperation: {
      create: {
        resourceName: budgetId,
        amountMicros: 10000000,
        explicitlyShared: false
      }
    }
  });
operations.push({
    campaignOperation: {
      create: {
        resourceName: campaignId,
        name: 'New Campaign ' + new Date(),
        advertisingChannelType: 'SEARCH',
        manualCpc: {},
        campaignBudget: budgetId,
        advertisingChannelType: 'DISPLAY',
        networkSettings: {
          targetContentNetwork: true
        }
      }
    }
  });
operations.push({
    adGroupOperation: {
      create: {
        campaign: campaignId,
        name: 'New AdGroup ' + new Date(),
        optimizedTargetingEnabled: true
      }
    }
  });
const results = AdsApp.mutateAll(
    operations, {partialFailure: false});