Trang này được dịch bởi Cloud Translation API.

Thay đổi

Tập lệnh Google Ads hỗ trợ các thay đổi chung có trong API Google Ads. Hầu hết các thao tác có thể thực hiện trong 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 phần lớn API Google Ads, nên bạn phải có hiểu biết 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 thành phần, chẳng hạn như mã của nhà phát triển và uỷ quyền, vì các thành phần này sẽ đượ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 thay đổi hợp lệ.

Dưới đây là một số tài nguyên cơ bản về giao diện Kiến trúc chuyển trạng thái đại diện (REST) của API Google Ads mà bạn nên làm quen trước khi tiếp tục theo 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 sau đâ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 đối tượng JSON đại diện cho một MutateOperation. Trong đối tượng này, bạn sẽ chỉ định loại thao tác mà mình đang thực hiện – trong trường hợp này là campaignBudgetOperation. Sau đó, bạn có thể 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 sử dụng.

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

Bạn có thể sử dụng một số chiến lược để xây dựng hoạt động hợp lệ. Bám sát 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ệ, 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 đối tượng thích hợp.

Ngoài ra, bạn có thể thử tạo hoạt động một cách linh động bằng cách sử dụng tính năng"Thử điều này" cho ngân sách chiến dịch. Tính năng này cho phép bạn tạo nội dung yêu cầu một cách linh động bằng cách chọn các trường mà 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ả được tạo và thêm vào lệnh gọi mutate sau khi chỉ định loại thao tác.

Loại hoạt động

Tạo

Chỉ định create trong thao tác, truyền vào một đối tượng đại diện cho tài nguyên 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, 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 thực thể đó bằng yêu cầu Adsapp.search.

Cập nhật

Chỉ định update trong thao tác, 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 bất kỳ trường nào mà bạn muốn cập nhật giá trị rồi 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ề toán tử 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 biến đổi và kiểm tra xem thao tác có thành công hay không hoặc có lỗi nào xảy ra (nếu có).

Dưới đây là ví dụ cho thấy 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 toán tử

Tập lệnh Google Ads cũng hỗ trợ việc thay đổi nhiều hoạt động 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ư toàn bộ hệ thống phân cấp chiến dịch trong một yêu cầu duy nhất. Bạn có thể tuỳ ý biến toàn bộ tập hợp thao tác thành nguyên tử, vì vậy nếu có 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 mảng cho mỗi toán tử mà bạn đã cung cấp và theo cùng thứ tự với các toán tử 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 về 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ã tạm thời và các điểm cần cân nhắc khác. Xin 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ã ngay 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 rồi gọi AdsApp.mutateAll. Lệnh gọi mutateAll lấy mảng toán tử 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ư V16, 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ể dùng mọi phiên bản công khai tại thời điểm đó.
partialFailure: Trường này mặc định là true. Nếu bạn đặ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 bị lỗi, thì sẽ không có thao tác nào được thực hiện, giúp tập hợp các thao tác này trở thành nguyên tử.

Dưới đây là một ví dụ với nhiều hoạt động 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 không thể phân chia.

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