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.

Thay đổi

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

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

Ví dụ cơ bản

Để minh hoạ chức năng này, hãy xem 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 thao tác.

Tạo 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ệ, 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 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 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 đại diện cho tài nguyên mà bạn muốn tạo.

Hãy xem đoạn mã được cung cấp trước đó để biết ví dụ về thao tác create.

Xoá

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 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 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 một updateMask cho biết chính xác những trường 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à một 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 có lỗi nào xảy ra hay không.

Dưới đây là ví dụ cho thấy 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 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ệ phân cấp chiến dịch đầy đủ trong một yêu cầu. Bạn có thể tuỳ ý đặt toàn bộ tập hợp thao tác thành nguyên tử, nhờ đó, nếu có một thao tác không thành công thì 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 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 Google Ads API, vì vậy, hãy tham khảo hướng dẫn về các phương pháp hay nhất cho Google Ads API để biết thông tin giải thích đầy đủ về mã tạm thời và các điểm cần lưu ý 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ã 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 của bạn vào một mảng rồi gọi AdsApp.mutateAll. Lệnh gọi mutateAll lấy mảng 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ư V26, 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 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ì khi 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, giúp tập hợp thao tác này trở thành một thao tác nguyên tử.

Dưới đâ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});

Thay đổi 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.