Thay đổi

Tập lệnh Google Ads hỗ trợ các thao tá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ể 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 như vậy của API Google Ads, nên bạn cần hiểu rõ các quy ước cơ bản 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à uỷ quyền, vì các khía cạnh đó được tập lệnh Google Ads xử lý cho bạn, nhưng bạn phải tạo một yêu cầu biến đổi hợp lệ.

Sau đâ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:

Ví dụ cơ bản

Để minh hoạ chức năng này, hãy xem xét ví dụ cơ bản này để 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 duy nhất. 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 thao tác.

Xây dựng một thao tác

Bạn có thể sử dụng một số chiến lược để tạo một thao tác 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 cho ngân sách chiến dịch để xem danh sách tất cả các trường hợp lệ của ngân sách đó, rồi đ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 phần nội dung yêu cầu một cách linh động bằng cách chọn những trường bạn muốn thêm. Sau đó, bạn có thể trích xuất nội dung của thao tác từ kết quả đã tạo và thêm nội dung đó vào lệnh gọi mutate sau khi chỉ định loại thao tác.

Loại thao tác

Tạo

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

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

Xóa

Chỉ định remove trong thao tác của bạn, truyền tên tài nguyên của tài nguyên mà 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ên đó bằ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 mà 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 một 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, giá trị trả về 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 biến đổi và kiểm tra xem thao tác có thành công hay không hoặc những lỗi nào đã xảy ra (nếu có).

Sau đây là ví dụ minh hoạ một 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 duy nhất. Bạn có thể tuỳ ý thực hiện toàn bộ tập hợp các thao tác 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 gồm các đối tượng MutateResult, một cho mỗi thao tác mà bạn cung cấp và theo cùng thứ tự với các thao tác 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 giải thích đầy đủ về mã nhận dạng tạm thời và các điểm 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ả các thao tác vào một mảng rồi 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 lựa 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ư V20, nếu muốn sử dụng một phiên bản khác với 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 cung cấp công khai tại thời điểm đó.
  • partialFailure: Trường này mặc định là true. Nếu được đặt thành true, thì các thao tác hợp lệ sẽ được thực hiện và các 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 có bất kỳ thao tác nào không thành công, hệ thống sẽ không thực hiện thao tác nào, nhờ đó, tập hợp thao tác này sẽ trở thành một thao tác nguyên tử.

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});