กลายพันธุ์

สคริปต์ Google Ads รองรับการเปลี่ยนแปลงทั่วไปที่มีใน Google Ads API การดำเนินการส่วนใหญ่ที่ทำได้จาก GoogleAdsService.mutate ก็ทำได้ในสคริปต์ Google Ads เช่นกัน ซึ่งรวมถึงการสร้างและจัดการแคมเปญ

เนื่องจากฟีเจอร์นี้อนุญาตให้เข้าถึง Google Ads API ได้เป็นจำนวนมาก จึงจำเป็นอย่างยิ่งที่จะต้องมีความเข้าใจพื้นฐานเกี่ยวกับข้อกำหนดของ Google Ads API เพื่อใช้ฟีเจอร์นี้ คุณข้ามหลายๆ ส่วนได้ เช่น โทเค็นของนักพัฒนาแอปและการให้สิทธิ์ เนื่องจากสคริปต์ Google Ads จะจัดการให้คุณ แต่คุณต้องสร้างคำขอเปลี่ยนแปลงข้อมูลในเซิร์ฟเวอร์ที่ถูกต้อง

ต่อไปนี้คือแหล่งข้อมูลพื้นฐานบางส่วนเกี่ยวกับอินเทอร์เฟซ REST ของ Google Ads API ที่คุณควรทำความคุ้นเคยก่อนที่จะอ่านคู่มือนี้ต่อ

• การออกแบบอินเทอร์เฟซ REST
• ชื่อทรัพยากร
• การแมป JSON
• เปลี่ยนแปลง

ตัวอย่างพื้นฐาน

หากต้องการแสดงฟังก์ชันการทำงาน ให้ดูตัวอย่างพื้นฐานนี้ซึ่งสร้างงบประมาณแคมเปญ

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

การเรียก AdsApp.mutate จะใช้ออบเจ็กต์ JSON ที่แสดง MutateOperationรายการเดียว ภายในออบเจ็กต์นี้ คุณระบุประเภทการดำเนินการที่จะทำ ซึ่งในกรณีนี้คือ campaignBudgetOperation จากนั้นระบุ create, remove หรือทั้ง update และ updateMask ฟิลด์เฉพาะภายใน create และ update จะขึ้นอยู่กับประเภททรัพยากรที่คุณดำเนินการ

สร้างการดำเนินการ

คุณสามารถใช้กลยุทธ์ 2-3 อย่างเพื่อสร้างการดำเนินการที่ถูกต้อง เมื่อใช้ตัวอย่างงบประมาณแคมเปญ คุณสามารถค้นหา เอกสารอ้างอิง REST สำหรับงบประมาณแคมเปญ เพื่อดูรายการฟิลด์ที่ถูกต้องทั้งหมด แล้วกรอกข้อมูลในฟิลด์ที่เหมาะสม หรือเขียนโค้ด JavaScript ที่กำหนดเองในสคริปต์เพื่อสร้าง ออบเจ็กต์ที่เหมาะสม

อีกวิธีหนึ่งคือ คุณสามารถลองสร้างการดำเนินการแบบไดนามิกโดยใช้ฟีเจอร์ "ลองใช้" สำหรับงบประมาณแคมเปญ, ซึ่งช่วยให้คุณสร้างเนื้อหาของคำขอแบบไดนามิกได้โดยเลือกฟิลด์ ที่ต้องการเพิ่ม จากนั้นแยกเนื้อหาของการดำเนินการออกจากผลลัพธ์ที่สร้างขึ้น แล้วเพิ่มลงในการเรียก mutate หลังจากระบุประเภทการดำเนินการ

ประเภทการดำเนินการ

สร้าง

ระบุ create ในการดำเนินการ โดยส่งการแสดงทรัพยากรในรูปแบบออบเจ็กต์ที่ต้องการสร้าง

ดูตัวอย่างการดำเนินการ create ในข้อมูลโค้ดที่ให้ไว้ก่อนหน้านี้

นำออก

ระบุ remove ในการดำเนินการ โดยส่ง ชื่อทรัพยากรของทรัพยากรที่คุณ ต้องการนำออก เช่น

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

หากไม่ทราบชื่อทรัพยากรของเอนทิตี คุณสามารถดึงข้อมูลดังกล่าวได้โดยใช้คำขอ Adsapp.search

อัปเดต

ระบุ update ในการดำเนินการ โดยส่งออบเจ็กต์ที่มีชื่อทรัพยากรที่ระบุเพื่อให้ระบบกำหนดได้ว่าคุณต้องการอัปเดตออบเจ็กต์ใด นอกจากนี้ ให้กรอกข้อมูลในฟิลด์ที่ต้องการอัปเดตค่า และระบุ updateMask ซึ่งจะระบุฟิลด์ที่คุณวางแผนจะเปลี่ยนแปลงในคำขอนี้อย่างชัดเจน อย่าใส่ชื่อทรัพยากรในมาสก์การอัปเดต

ตัวอย่างการดำเนินการ update

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

จัดการผลลัพธ์

ไม่ว่าการดำเนินการจะเป็นประเภทใด ค่าที่แสดงจะเป็น MutateResult คุณสามารถใช้ชื่อทรัพยากรที่แสดงเพื่อค้นหาสถานะปัจจุบันของทรัพยากรหลังจากการเปลี่ยนแปลง และตรวจสอบว่าการดำเนินการสำเร็จหรือไม่ หรือมีข้อผิดพลาดใดเกิดขึ้น

ต่อไปนี้เป็นตัวอย่างที่แสดงขั้นตอนพื้นฐานสำหรับการตรวจสอบผลลัพธ์และการพิมพ์ข้อมูลบางอย่างลงในบันทึก

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

การดำเนินการหลายรายการ

สคริปต์ Google Ads ยังรองรับการเปลี่ยนแปลงการดำเนินการหลายรายการในคำขอเดียวด้วย เมธอด AdsApp.mutateAll คุณสามารถสร้างเอนทิตีที่ขึ้นอยู่กับเอนทิตีอื่นๆ เช่น ลำดับชั้นของแคมเปญทั้งหมดในคำขอเดียว นอกจากนี้ คุณยังเลือกทำให้ชุดการดำเนินการทั้งหมดเป็นแบบอะตอมมิกได้ด้วย ซึ่งหมายความว่าหากการดำเนินการใดรายการหนึ่งล้มเหลว ระบบจะไม่ดำเนินการรายการอื่นๆ

ค่าที่แสดงจะเป็นอาร์เรย์ของ MutateResult ออบเจ็กต์ ซึ่งมีออบเจ็กต์หนึ่งรายการสำหรับการดำเนินการแต่ละรายการที่คุณระบุ และอยู่ในลำดับเดียวกับการดำเนินการ เริ่มต้น

ฟีเจอร์นี้ทำงานเหมือนกับฟีเจอร์ Google Ads API ดังนั้นโปรดดูคำอธิบายโดยละเอียดเกี่ยวกับรหัสชั่วคราวและข้อควรพิจารณาอื่นๆ ใน คู่มือแนวทางปฏิบัติแนะนำของ Google Ads API โปรดทราบว่าคู่มือดังกล่าวใช้ snake_case เพื่อแสดงชื่อฟิลด์ ขณะที่เอกสารประกอบของสคริปต์ Google Ads ใช้ lowerCamelCase สคริปต์ Google Ads ยอมรับทั้ง 2 กรณีนี้ คุณจึงคัดลอกโค้ดจากคู่มือดังกล่าวได้โดยตรง

หากต้องการดำเนินการหลายรายการในคำขอเดียว ให้รวบรวมการดำเนินการทั้งหมดลงในอาร์เรย์ แล้วเรียก AdsApp.mutateAll การเรียก mutateAll จะใช้อาร์เรย์ของการดำเนินการเป็นอาร์กิวเมนต์แรก และอาร์กิวเมนต์ที่ 2 ที่ไม่บังคับเป็นตัวเลือก ซึ่งรวมถึง

• apiVersion: คุณสามารถระบุเวอร์ชัน API ที่กำหนดเอง เช่น V26 หากต้องการใช้เวอร์ชันอื่นที่ไม่ใช่เวอร์ชันเริ่มต้นของสคริปต์ คุณสามารถใช้เวอร์ชันที่เผยแพร่ต่อสาธารณะได้ทุกเวอร์ชันในขณะนั้น
• partialFailure: ฟิลด์นี้มีค่าเริ่มต้นเป็น true หากตั้งค่าเป็น true ระบบจะดำเนินการที่ถูกต้องและแสดงข้อผิดพลาดสำหรับการดำเนินการที่ล้มเหลว หากตั้งค่าเป็น false หากการดำเนินการใดรายการหนึ่งล้มเหลว ระบบจะไม่ดำเนินการรายการอื่นๆ ซึ่งทำให้ชุดการดำเนินการนี้เป็นแบบอะตอมมิก

ต่อไปนี้เป็นตัวอย่างที่มีการดำเนินการหลายรายการ ซึ่งสร้างงบประมาณแคมเปญ แคมเปญ และกลุ่มโฆษณาในคำขอแบบอะตอมมิก

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