API บุคคลที่สาม

ฟีเจอร์ที่มีประสิทธิภาพของสคริปต์ Google Ads คือความสามารถในการผสานรวมกับข้อมูลและบริการจาก API ของบุคคลที่สาม

คู่มือนี้ครอบคลุมแนวคิดต่อไปนี้ซึ่งจะช่วยคุณเขียนสคริปต์เพื่อเชื่อมต่อกับบริการอื่นๆ

• การส่งคําขอ HTTP: วิธีใช้ UrlFetchApp เพื่อเข้าถึง API ภายนอก
• การตรวจสอบสิทธิ์: เราอธิบายสถานการณ์การตรวจสอบสิทธิ์ที่พบได้ทั่วไป
• การแยกวิเคราะห์การตอบกลับ: วิธีประมวลผลข้อมูล JSON และ XML ที่แสดงผล

นอกจากนี้ เรายังมีตัวอย่าง API ยอดนิยมจำนวนหนึ่งที่แสดงแนวคิดเหล่านี้

หมายเหตุ: ในการเขียนหรือใช้สคริปต์ที่ใช้ API ของบุคคลที่สาม เราขอแนะนำให้อ่านข้อกำหนดในการให้บริการที่เชื่อมโยงกับ API เพื่อให้แน่ใจว่าการใช้งานตามที่ต้องการเป็นไปตามข้อกำหนดดังกล่าว

ดึงข้อมูลด้วย UrlFetchApp

UrlFetchApp มีฟังก์ชันหลักที่จําเป็นสําหรับการโต้ตอบกับ API ของบุคคลที่สาม

หมายเหตุ: UrlFetchApp เป็นพื้นฐานในการโต้ตอบกับ API ของบุคคลที่สาม แต่ก็มีโควต้าในการใช้งานที่คุณควรทราบเมื่อพัฒนาโซลูชัน

ตัวอย่างต่อไปนี้แสดงการดึงข้อมูลสภาพอากาศจาก OpenWeatherMap เราเลือก OpenWeatherMap เนื่องจากรูปแบบการให้สิทธิ์และ API ที่ค่อนข้างง่าย

ส่งคำขอ

เอกสารประกอบของ OpenWeatherMap ระบุรูปแบบในการขอสภาพอากาศปัจจุบันดังนี้

http://api.openweathermap.org/data/2.5/weather?q=[location]&apikey=[apikey]

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

หลังจากลงชื่อสมัครใช้แล้ว คุณส่งคำขอโดยใช้คีย์ได้โดยทำดังนี้

const location = 'London,uk';
const apikey = 'da.......................81'; // Replace with your API key
const currentWeatherUrl = `http://api.openweathermap.org/data/2.5/weather?q=${location}&apiKey=${apiKey}`;
const response = UrlFetchApp.fetch(currentWeatherUrl);
console.log(response.getContentText());

การดำเนินการกับโค้ดนี้จะส่งผลให้มีสตริง JSON ยาวๆ เขียนลงในหน้าต่างการบันทึกในสคริปต์ Google Ads

ขั้นตอนถัดไปคือการแปลงข้อมูลนี้ให้เป็นรูปแบบที่ใช้ได้ภายในสคริปต์

ข้อมูล JSON

API จํานวนมากให้คําตอบในรูปแบบ JSON ซึ่งแสดงการแปลงเป็นอนุกรมแบบง่ายของออบเจ็กต์ JavaScript เพื่อให้แสดงและโอนออบเจ็กต์ อาร์เรย์ และประเภทพื้นฐานเป็นสตริงได้

หากต้องการแปลงสตริง JSON เช่น สตริงที่แสดงผลจาก OpenWeatherMap กลับเป็นออบเจ็กต์ JavaScript ให้ใช้เมธอด JSON.parse ในตัว ต่อจากตัวอย่างด้านบน

const json = response.getContentText();
const weatherData = JSON.parse(json);
console.log(weatherData.name);
//  "London"

เมธอด JSON.parse จะแปลงสตริงให้เป็นออบเจ็กต์ซึ่งมีพร็อพเพอร์ตี้ name

ดูรายละเอียดเพิ่มเติมเกี่ยวกับการทำงานกับคำตอบของ API ในรูปแบบต่างๆ ได้ที่ส่วนแยกวิเคราะห์คำตอบ

การจัดการข้อผิดพลาด

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

• URL หรือพารามิเตอร์ของ API อาจเปลี่ยนแปลงโดยที่คุณไม่ทราบ
• คีย์ API (หรือข้อมูลเข้าสู่ระบบของผู้ใช้อื่นๆ) อาจหมดอายุ
• รูปแบบของคำตอบอาจเปลี่ยนแปลงได้โดยไม่ต้องแจ้งให้ทราบ

รหัสสถานะ HTTP

คุณควรตรวจสอบรหัสสถานะ HTTP เนื่องจากอาจมีการตอบกลับที่ไม่คาดคิด โดยค่าเริ่มต้น UrlFetchApp จะแสดงข้อยกเว้นหากพบรหัสข้อผิดพลาด HTTP หากต้องการเปลี่ยนลักษณะการทํางานนี้ คุณต้องส่งพารามิเตอร์ที่ไม่บังคับ ดังตัวอย่างต่อไปนี้

const options = {
  muteHttpExceptions: true
}
const response = UrlFetchApp.fetch(url, options);
// Any status code greater or equal to 400 is either a client or server error.
if (response.getResponseCode() >= 400) {
  // Error encountered, send an email alert to the developer
  sendFailureEmail();
}

โครงสร้างคำตอบ

เมื่อ API ของบุคคลที่สามมีการเปลี่ยนแปลง นักพัฒนาแอปมักไม่ทราบถึงการเปลี่ยนแปลงที่อาจส่งผลต่อสคริปต์ของตนในทันที ตัวอย่างเช่น หากมีการเปลี่ยนแปลงพร็อพเพอร์ตี้ name ที่แสดงผลในตัวอย่าง OpenWeatherMap เป็น locationName สคริปต์ที่ใช้พร็อพเพอร์ตี้นี้จะใช้งานไม่ได้

ด้วยเหตุนี้ คุณจึงควรทดสอบว่าโครงสร้างที่แสดงผลเป็นไปตามที่คาดไว้หรือไม่ เช่น

const weatherData = JSON.parse(json);
if (weatherData && weatherData.name) {
  console.log('Location is : ' + name);
} else {
  console.log('Data not in expected format');
}

ข้อมูล POST ด้วย UrlFetchApp

ตัวอย่างเบื้องต้นที่ใช้ OpenWeatherMap จะดึงข้อมูลเท่านั้น โดยปกติแล้ว การเรียก API ที่ไม่เปลี่ยนสถานะในเซิร์ฟเวอร์ระยะไกลจะใช้เมธอด HTTP GET

เมธอด GET เป็นค่าเริ่มต้นของ UrlFetchApp อย่างไรก็ตาม การเรียก API บางรายการ เช่น การเรียกบริการที่ส่งข้อความ SMS จะใช้วิธีการอื่นๆ เช่น POST หรือ PUT

ตัวอย่างต่อไปนี้แสดงการผสานรวมกับ Slack ซึ่งเป็นแอปพลิเคชันการรับส่งข้อความแบบทำงานร่วมกัน เพื่อส่งข้อความ Slack ไปยังผู้ใช้และกลุ่ม Slack เพื่อแสดงให้เห็นการใช้การเรียกใช้ POST กับ UrlFetchApp

ตั้งค่า Slack

คู่มือนี้จะถือว่าคุณได้ลงชื่อสมัครใช้บัญชี Slack แล้ว

เช่นเดียวกับ OpenWeatherMap ในตัวอย่างก่อนหน้านี้ คุณจำเป็นต้องรับโทเค็นเพื่อเปิดใช้การส่งข้อความ Slack มี URL ที่ไม่ซ้ำกันซึ่งช่วยให้คุณส่งข้อความถึงทีมได้ ซึ่งเรียกว่า Incoming Webhook

ตั้งค่า Webhook ขาเข้าโดยคลิกเพิ่มการผสานรวม Webhook ขาเข้า แล้วทําตามวิธีการ กระบวนการนี้ควรออก URL ที่ใช้รับส่งข้อความ

ส่งคําขอ POST

เมื่อตั้งค่า Webhook ขาเข้าแล้ว การสร้างคําขอ POST ต้องใช้พร็อพเพอร์ตี้เพิ่มเติมบางอย่างในพารามิเตอร์ options ที่ส่งไปยัง UrlFetchApp.fetch ดังนี้

• method: ดังที่ได้กล่าวไว้ ค่าเริ่มต้นของพารามิเตอร์นี้คือ GET แต่เราจะลบล้างค่านี้และตั้งค่าเป็น POST

• payload: นี่คือข้อมูลที่ส่งไปยังเซิร์ฟเวอร์เป็นส่วนหนึ่งของPOSTคำขอ ในตัวอย่างนี้ Slack คาดหวังว่าออบเจ็กต์จะได้รับการแปลงเป็นรูปแบบ JSON ตามที่อธิบายไว้ในเอกสารประกอบของ Slack ในกรณีนี้ ระบบจะใช้วิธี JSON.stringify และตั้งค่า Content-Type เป็น application/json

    // Change the URL for the one issued to you from 'Setting up Slack'.
    const SLACK_URL = 'https://hooks.slack.com/services/AAAA/BBBB/CCCCCCCCCC';
    const slackMessage = {
      text: 'Hello, slack!'
    };
  
    const options = {
      method: 'POST',
      contentType: 'application/json',
      payload: JSON.stringify(slackMessage)
    };
    UrlFetchApp.fetch(SLACK_URL, options);
  

ตัวอย่าง Slack แบบขยาย

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

ดูรายละเอียดเพิ่มเติมเกี่ยวกับข้อความ Slack ได้ที่การจัดรูปแบบข้อความในเอกสารประกอบของ Slack

ข้อมูลฟอร์ม

ตัวอย่างด้านบนแสดงการใช้สตริง JSON เป็นพร็อพเพอร์ตี้ payload สำหรับคำขอ POST

UrlFetchApp ใช้แนวทางที่แตกต่างกันในการสร้างคําขอ POST โดยขึ้นอยู่กับรูปแบบของ payload ดังนี้

• เมื่อ payload เป็นสตริง ระบบจะส่งอาร์กิวเมนต์สตริงเป็นเนื้อหาของคําขอ

• เมื่อ payload ออบเจ็กต์ เช่น แผนที่ของค่า

  {to: '[e-mail]', subject:'Test', body:'Hello, World!'}
  

  ระบบจะแปลงคู่คีย์/ค่าเป็น Form Data ดังนี้

  subject=Test&to=[e-mail]&body=Hello,+World!
  

  นอกจากนี้ ระบบยังตั้งค่าส่วนหัว Content-Type ของคําขอเป็น application/x-www-form-urlencoded

API บางรายการต้องใช้ข้อมูลแบบฟอร์มเมื่อส่งคําขอ POST คุณจึงควรทราบถึงการเปลี่ยนรูปแบบจากออบเจ็กต์ JavaScript เป็นข้อมูลแบบฟอร์มโดยอัตโนมัติ

การตรวจสอบสิทธิ์พื้นฐาน HTTP

การตรวจสอบสิทธิ์พื้นฐานของ HTTP เป็นหนึ่งในรูปแบบการตรวจสอบสิทธิ์ที่ง่ายที่สุดและ API หลายรายการใช้

การตรวจสอบสิทธิ์ทำได้โดยการแนบชื่อผู้ใช้และรหัสผ่านที่เข้ารหัสไว้กับส่วนหัว HTTP ในคําขอแต่ละรายการ

สร้างคําขอ

คุณต้องทําตามขั้นตอนต่อไปนี้เพื่อสร้างคําขอที่มีการตรวจสอบสิทธิ์

1. สร้างรหัสผ่านโดยต่อชื่อผู้ใช้และรหัสผ่านด้วยโคลอน เช่น username:password
2. เข้ารหัสรหัสผ่านด้วย Base64 เช่น username:password จะกลายเป็น dXNlcm5hbWU6cGFzc3dvcmQ=
3. แนบส่วนหัว Authorization กับคำขอในรูปแบบ Authorization: Basic <encoded passphrase>

ข้อมูลโค้ดต่อไปนี้แสดงวิธีดำเนินการนี้ในสคริปต์ Google Ads

const USERNAME = 'your_username';
const PASSWORD = 'your_password';
const API_URL = 'http://<place_api_url_here>';

const authHeader = 'Basic ' + Utilities.base64Encode(USERNAME + ':' + PASSWORD);
const options = {
  headers: {Authorization: authHeader}
}
// Include 'options' object in every request
const response = UrlFetchApp.fetch(API_URL, options);

ตัวอย่างการตรวจสอบสิทธิ์พื้นฐาน

ส่วนตัวอย่างโค้ดมีตัวอย่าง 2 รายการที่แสดงการใช้การตรวจสอบสิทธิ์พื้นฐานของ HTTP ดังนี้

• การส่งข้อความ SMS ผ่าน Plivo
• การส่งข้อความ SMS ผ่าน Twilio

Plivo

Plivo เป็นบริการที่อำนวยความสะดวกในการส่งและรับข้อความ SMS ผ่าน API ตัวอย่างนี้แสดงการส่งข้อความ

1. ลงทะเบียนกับ Plivo
2. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
3. แทนที่ค่า PLIVO_ACCOUNT_AUTHID และ PLIVO_ACCOUNT_AUTHTOKEN ด้วยค่าจากหน้าแดชบอร์ดการจัดการ
4. แทรกอีเมลตามที่ระบุไว้ในสคริปต์เพื่อรับการแจ้งเตือนข้อผิดพลาด
5. หากต้องการใช้ Plivo คุณต้องซื้อหมายเลขหรือเพิ่มหมายเลขลงในบัญชีช่วงทดลองใช้ เพิ่มหมายเลขแซนด์บ็อกซ์ที่ใช้กับบัญชีทดลองได้
6. เพิ่มทั้งหมายเลขที่จะปรากฏเป็นผู้ส่งและหมายเลขผู้รับ
7. อัปเดต PLIVO_SRC_PHONE_NUMBER ในสคริปต์เป็นหมายเลขที่อยู่ในแซนด์บ็อกซ์ซึ่งเพิ่งจดทะเบียน ซึ่งควรมีรหัสประเทศระหว่างประเทศ เช่น 447777123456 สำหรับหมายเลขในสหราชอาณาจักร

Twilio

Twilio เป็นบริการอีกอย่างที่อำนวยความสะดวกในการส่งและรับข้อความ SMS ผ่าน API ตัวอย่างนี้แสดงการส่งข้อความ

1. ลงทะเบียนกับ Twillio
2. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
3. แทนที่ค่า TWILIO_ACCOUNT_SID และ TWILIO_ACCOUNT_AUTHTOKEN ด้วยค่าที่แสดงในหน้าคอนโซลบัญชี
4. แทนที่ TWILIO_SRC_PHONE_NUMBER ด้วยหมายเลขจากหน้าแดชบอร์ด ซึ่งเป็นหมายเลขที่ Twilio อนุญาตให้ส่งข้อความ

OAuth 1.0

บริการยอดนิยมหลายอย่างใช้ OAuth ในการตรวจสอบสิทธิ์ OAuth มีหลากหลายรูปแบบและเวอร์ชัน

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

ดูข้อมูลเบื้องต้นเกี่ยวกับ OAuth 1.0 ได้ที่คู่มือ OAuth Core โดยเฉพาะอย่างยิ่ง โปรดดูที่ 6. การตรวจสอบสิทธิ์ด้วย OAuth ใน OAuth 1.0 แบบ3 ขาเต็มรูปแบบ กระบวนการมีดังนี้

1. แอปพลิเคชัน ("ผู้บริโภค") จะได้รับโทเค็นคำขอ
2. ผู้ใช้ให้สิทธิ์โทเค็นคำขอ
3. แอปพลิเคชันจะแลกเปลี่ยนโทเค็นคำขอเป็นโทเค็นการเข้าถึง
4. สำหรับคำขอทรัพยากรทั้งหมดที่ตามมา ระบบจะใช้โทเค็นการเข้าถึงในคำขอที่ลงชื่อ

หากบริการของบุคคลที่สามต้องการใช้ OAuth 1.0 โดยไม่ต้องมีการโต้ตอบกับผู้ใช้ (เช่น ตามที่สคริปต์ Google Ads กำหนด) ขั้นตอนที่ 1, 2 และ 3 จะดำเนินการไม่ได้ ดังนั้น บริการบางรายการจึงออกโทเค็นการเข้าถึงจากคอนโซลการกําหนดค่า ซึ่งช่วยให้แอปพลิเคชันไปยังขั้นตอนที่ 4 ได้โดยตรง ซึ่งเรียกว่า OAuth 1.0 แบบ 1 ทาง

OAuth 1.0 ในสคริปต์ Google Ads

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

• ตั้งค่าการกําหนดค่าแอปพลิเคชันเพื่อแสดงสคริปต์
• ระบุสิทธิ์ที่จะขยายไปยังสคริปต์
• รับคีย์ผู้ใช้ ข้อมูลลับของผู้ใช้ โทเค็นการเข้าถึง และข้อมูลลับการเข้าถึงเพื่อใช้กับ OAuth แบบ 1 ทาง

OAuth 2.0

OAuth 2.0 ใช้กับ API ยอดนิยมเพื่อให้สิทธิ์เข้าถึงข้อมูลผู้ใช้ เจ้าของบัญชีบริการของบุคคลที่สามจะให้สิทธิ์แก่แอปพลิเคชันบางรายการเพื่ออนุญาตให้เข้าถึงข้อมูลผู้ใช้ ข้อดีคือเจ้าของจะดำเนินการต่อไปนี้ได้

• ไม่ต้องแชร์ข้อมูลเข้าสู่ระบบบัญชีกับแอปพลิเคชัน
• ควบคุมได้ว่าแอปพลิเคชันใดบ้างที่มีสิทธิ์เข้าถึงข้อมูลและเข้าถึงข้อมูลในระดับใด (เช่น สิทธิ์เข้าถึงที่มอบอาจเป็นสิทธิ์อ่านอย่างเดียว หรือสิทธิ์เข้าถึงข้อมูลชุดย่อยเท่านั้น)

หากต้องการใช้บริการที่เปิดใช้ OAuth 2.0 ในสคริปต์ Google Ads คุณต้องทำตามขั้นตอนต่อไปนี้

ภายนอกสคริปต์

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

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

ในสคริปต์

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

ส่งคําขอ API ส่งโทเค็นการเข้าถึงพร้อมกับคำขอแต่ละรายการ

ขั้นตอนการให้สิทธิ์

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

ผู้ให้บริการ API จะเป็นผู้ตัดสินใจว่าจะยอมรับการให้สิทธิ์ประเภทใด ซึ่งจะเป็นแนวทางให้ผู้ใช้ผสานรวม API ต่อไป

การใช้งาน

เป้าหมายของขั้นตอน OAuth ทั้งหมดคือรับโทเค็นการเข้าถึง ซึ่งจะใช้ในเซสชันที่เหลือเพื่อตรวจสอบสิทธิ์คำขอได้

คลังตัวอย่างแสดงวิธีตรวจสอบสิทธิ์สำหรับแต่ละประเภทของขั้นตอน โดยแต่ละเมธอดจะแสดงผลออบเจ็กต์ที่รับและจัดเก็บโทเค็นการเข้าถึง รวมถึงอำนวยความสะดวกให้กับคำขอที่ตรวจสอบสิทธิ์แล้ว

รูปแบบการใช้งานทั่วไปมีดังนี้

// Authenticate using chosen flow type
const urlFetchObj = OAuth2.<flow method>(args);
// Make request(s) using obtained object.
const response1 = urlFetchObj.fetch(url1);
const response2 = urlFetchObj.fetch(url2, options);

หมายเหตุ: เนื่องจากสคริปต์ Google Ads มีอายุสั้น ไลบรารีตัวอย่างนี้จึงไม่พยายามรีเฟรชโทเค็นการเข้าถึงที่ได้รับ

การให้สิทธิ์ข้อมูลเข้าสู่ระบบของไคลเอ็นต์

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

// Access token is obtained and cached.
const authUrlFetch = OAuth2.withClientCredentials(
    tokenUrl, clientId, clientSecret, optionalScope));
// Use access token in each request
const response = authUrlFetch.fetch(url);
// ... use response

การให้โทเค็นการรีเฟรช

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

รับโทเค็นการรีเฟรช

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

การใช้ OAuth Playground เพื่อรับโทเค็นการรีเฟรช

OAuth2 Playground มี UI ที่ช่วยให้ผู้ใช้ดำเนินการตามขั้นตอนการให้สิทธิ์รหัสการให้สิทธิ์เพื่อรับโทเค็นการรีเฟรช

ปุ่มการตั้งค่าที่ด้านขวาบนช่วยให้คุณกําหนดพารามิเตอร์ทั้งหมดที่จะใช้ในขั้นตอนการขอสิทธิ์ OAuth ได้ ซึ่งรวมถึง

• ปลายทางการให้สิทธิ์: ใช้เป็นการเริ่มต้นขั้นตอนการให้สิทธิ์
• ปลายทางของโทเค็น: ใช้กับโทเค็นการรีเฟรชเพื่อรับโทเค็นการเข้าถึง
• รหัสไคลเอ็นต์และรหัสลับ: ข้อมูลเข้าสู่ระบบสําหรับแอปพลิเคชัน

การใช้สคริปต์เพื่อรับโทเค็นรีเฟรช

ทางเลือกที่ใช้สคริปต์แทนการทำตามขั้นตอนให้เสร็จสมบูรณ์มีอยู่ในตัวอย่างการสร้างโทเค็นรีเฟรช

การใช้โทเค็นการรีเฟรช

เมื่อดำเนินการให้สิทธิ์ครั้งแรกแล้ว บริการจะออกโทเค็นรีเฟรชซึ่งจะใช้ในลักษณะคล้ายกับขั้นตอนการให้สิทธิ์ของไคลเอ็นต์ได้ ตัวอย่าง 2 รายการมีดังนี้

const authUrlFetch = OAuth2.withRefreshToken(tokenUrl, clientId, clientSecret,
    refreshToken, optionalScope);
const response = authUrlFetch.fetch(url);
// ... use response

ตัวอย่าง Search Ads 360

Search Ads 360 เป็นตัวอย่างของ API ที่สามารถใช้กับโทเค็นรีเฟรชได้ ในตัวอย่างนี้ สคริปต์จะสร้างและแสดงรายงาน ดูรายละเอียดการดำเนินการอื่นๆ ที่ทำได้ทั้งหมดในเอกสารอ้างอิง Search Ads 360 API

สร้างสคริปต์

1. สร้างโปรเจ็กต์ใหม่ในคอนโซล API และรับรหัสไคลเอ็นต์ ข้อมูลลับไคลเอ็นต์ และโทเค็นรีเฟรชโดยทําตามขั้นตอนในคู่มือ DoubleClick และตรวจสอบว่าคุณเปิดใช้ DoubleClick Search API แล้ว
2. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
3. วางตัวอย่างไลบรารี OAuth2 ใต้รายการโค้ด
4. แก้ไขสคริปต์ให้มีค่าที่ถูกต้องสำหรับรหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ และโทเค็นรีเฟรช

ตัวอย่าง Apps Script Execution API

ตัวอย่างนี้แสดงการเรียกใช้ฟังก์ชันใน Apps Script โดยใช้ Apps Script Execution API ซึ่งจะช่วยให้เรียกใช้ Apps Script จากสคริปต์ Google Ads ได้

สร้างสคริปต์ Apps Script

สร้างสคริปต์ใหม่ ตัวอย่างต่อไปนี้จะแสดงรายการไฟล์ 10 รายการจากไดรฟ์

function listFiles() {
  const limit = 10;
  const files = [];
  const fileIterator = DriveApp.getFiles();
  while (fileIterator.hasNext() && limit) {
    files.push(fileIterator.next().getName());
    limit--;
  }
  return files;
}

กำหนดค่า Apps Script เพื่อเรียกใช้

1. บันทึกสคริปต์
2. คลิกทรัพยากร > โปรเจ็กต์ Cloud Platform
3. คลิกชื่อโปรเจ็กต์เพื่อไปยังคอนโซล API
4. ไปที่ API และบริการ
5. เปิดใช้ API ที่เหมาะสม ซึ่งในกรณีนี้คือ Drive API และ Apps Script Execution API
6. สร้างข้อมูลเข้าสู่ระบบ OAuth จากรายการข้อมูลเข้าสู่ระบบในเมนู
7. กลับไปที่สคริปต์ แล้วเผยแพร่สคริปต์เพื่อเรียกใช้จากเผยแพร่ > ทำให้ใช้งานได้เป็นไฟล์ดำเนินการของ API

สร้างสคริปต์ Google Ads

1. วางตัวอย่างสคริปต์ลงในสคริปต์ใหม่ใน Google Ads
2. นอกจากนี้ ให้วางตัวอย่างไลบรารี OAuth2 ใต้รายการโค้ด
3. แก้ไขสคริปต์ให้มีค่าที่ถูกต้องสำหรับรหัสไคลเอ็นต์ รหัสลับไคลเอ็นต์ และโทเค็นรีเฟรช

บัญชีบริการ

แนวคิดของบัญชีบริการเป็นอีกทางเลือกหนึ่งนอกเหนือจากการให้สิทธิ์ประเภทข้างต้น

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

ตัวอย่าง Google Natural Language API

Natural Language API ให้การวิเคราะห์ความรู้สึกและการวิเคราะห์เอนทิตีสําหรับข้อความ

ตัวอย่างนี้แสดงการคํานวณความรู้สึกสําหรับข้อความโฆษณา ซึ่งรวมถึงบรรทัดแรกหรือคําอธิบาย ข้อมูลนี้ช่วยวัดระดับความบวกของข้อความและระดับของข้อความได้ เราขายเค้กหรือเราขายเค้กที่ดีที่สุดในลอนดอนข้อความใดดีกว่า ซื้อเลย

ตั้งค่าสคริปต์

1. สร้างโปรเจ็กต์ใหม่ในคอนโซล API
2. เปิดใช้ Natural Language API
3. เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์
4. สร้างบัญชีบริการ ดาวน์โหลดไฟล์ JSON ของข้อมูลเข้าสู่ระบบ
5. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
6. นอกจากนี้ ให้วางตัวอย่างไลบรารี OAuth2 ใต้รายการโค้ด
7. แทนที่ค่าที่จําเป็น ดังนี้
   • serviceAccount: อีเมลของบัญชีบริการ เช่น [e-mail]
   • key: คีย์จากไฟล์ JSON ที่ดาวน์โหลดเมื่อสร้างบัญชีบริการ เริ่มต้น -----BEGIN PRIVATE KEY... และสิ้นสุด ...END PRIVATE KEY-----\n

การตอบกลับจาก API

API สามารถแสดงผลข้อมูลได้หลายรูปแบบ รูปแบบที่โดดเด่นที่สุดคือ XML และ JSON

JSON

โดยทั่วไปแล้ว JSON ใช้งานได้ง่ายกว่า XML ในรูปแบบคำตอบ อย่างไรก็ตาม ยังคงมีปัญหาบางอย่างที่อาจเกิดขึ้นได้

การตรวจสอบการตอบกลับ

เมื่อได้รับการตอบกลับที่สำเร็จจากการเรียก API แล้ว ขั้นตอนถัดไปโดยทั่วไปคือการใช้ JSON.parse เพื่อแปลงสตริง JSON เป็นออบเจ็กต์ JavaScript เมื่อถึงจุดนี้ คุณควรจัดการกรณีที่การแยกวิเคราะห์ไม่สําเร็จ

const json = response.getContentText();
try {
  const data = JSON.parse(json);
  return data;
} catch(e) {
  // Parsing of JSON failed - handle error.
}

นอกจากนี้ หาก API ไม่ได้อยู่ภายใต้การควบคุมของคุณ โปรดทราบว่าโครงสร้างของคำตอบอาจเปลี่ยนแปลงไปและพร็อพเพอร์ตี้อาจไม่มีอยู่อีกต่อไป

// Less good approach
// Assumes JSON was in form {"queryResponse": ...} when parsed.
const answer = data.queryResponse;

// Better approach
if (data && data.queryResponse) {
  const answer = data.queryResponse;
} else {
  // Format of API response has changed - alert developer or handle accordingly
}

XML

การตรวจสอบความถูกต้อง

XML ยังคงเป็นรูปแบบที่ได้รับความนิยมในการสร้าง API การตอบกลับจากการเรียก API สามารถแยกวิเคราะห์ได้โดยใช้เมธอด XmlService parse ดังนี้

const responseText = response.getContentText();
try {
  const document = XmlService.parse(responseText);
} catch(e) {
  // Error in XML representation - handle accordingly.
}

แม้ว่า XmlService.parse จะตรวจหาข้อผิดพลาดใน XML และแสดงข้อยกเว้นตามความเหมาะสม แต่ก็ไม่ได้ให้ความสามารถในการตรวจสอบ XML กับสคีมา

องค์ประกอบรูท

เมื่อแยกวิเคราะห์เอกสาร XML สำเร็จแล้ว ระบบจะรับองค์ประกอบรูทโดยใช้เมธอด getRootElement() ดังนี้

const document = XmlService.parse(responseText);
const rootElement = document.getRootElement();

เนมสเปซ

ในตัวอย่างนี้ ระบบจะใช้ Sportradar API เพื่อรับผลการแข่งขันฟุตบอลของการแข่งขันที่เลือก การตอบกลับ XML จะมีรูปแบบดังนี้

<schedule xmlns="http://feed.elasticstats.com/schema/soccer/sr/v2/matches-schedule.xsd">
  <matches>
     ...
  </matches>
</schedule>

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

• ดึงข้อมูลแอตทริบิวต์เนมสเปซจากเอกสาร
• ใช้เนมสเปซนี้เมื่อไปยังส่วนต่างๆ และเข้าถึงองค์ประกอบย่อย

ตัวอย่างต่อไปนี้แสดงวิธีเข้าถึงองค์ประกอบ <matches> ในข้อมูลโค้ดเอกสารด้านบน

const document = XmlService.parse(xmlText);
const scheduleElement = document.getRootElement();
// The namespace is required for accessing child elements in the schema.
const namespace = scheduleElement.getNamespace();
const matchesElement = scheduleElement.getChild('matches', namespace);

รับค่า

จากตัวอย่างกำหนดเวลาการแข่งขันฟุตบอล

<match status="..." category="..." ... >
  ...
</match>

คุณสามารถเรียกข้อมูลแอตทริบิวต์ได้ เช่น

const status = matchElement.getAttribute('status').getValue();

ระบบจะอ่านข้อความภายในองค์ประกอบได้โดยใช้ getText() แต่ระบบจะต่อข้อความเหล่านี้เข้าด้วยกันเมื่อมีองค์ประกอบย่อยที่เป็นข้อความหลายรายการ ลองใช้ getChildren() และวนซ้ำผ่านรายการย่อยแต่ละรายการในกรณีที่มีรายการย่อยที่เป็นข้อความหลายรายการ

ตัวอย่าง Sportradar

ตัวอย่าง เต็มรูปแบบของ Sportradar นี้แสดงการดึงข้อมูลรายละเอียดการแข่งขันฟุตบอล โดยเฉพาะการแข่งขันพรีเมียร์ลีกอังกฤษ Soccer APIเป็นหนึ่งในฟีดกีฬาที่หลากหลายซึ่ง Sportradar นำเสนอ

ตั้งค่าบัญชี Sportradar

1. ไปที่เว็บไซต์ของนักพัฒนาแอป Sportradar
2. ลงทะเบียนบัญชีทดลองใช้
3. เมื่อลงทะเบียนแล้ว ให้ลงชื่อเข้าใช้บัญชี
4. เมื่อเข้าสู่ระบบแล้ว ให้ไปที่MyAccount

Sportradar จะแยกกีฬาแต่ละประเภทออกเป็น API ที่แตกต่างกัน ตัวอย่างเช่น คุณอาจซื้อสิทธิ์เข้าถึง Soccer API แต่ไม่ได้ซื้อสิทธิ์เข้าถึง Tennis API แอปพลิเคชันแต่ละรายการที่คุณสร้างอาจเชื่อมโยงกับกีฬาที่แตกต่างกันและมีคีย์ที่แตกต่างกัน

1. ในส่วนแอปพลิเคชัน ให้คลิกสร้างแอปพลิเคชันใหม่ ตั้งชื่อและคำอธิบายแอปพลิเคชัน แล้วละเว้นช่องเว็บไซต์
2. เลือกเฉพาะออกคีย์ใหม่สำหรับ Soccer Trial Europe v2
3. คลิกลงทะเบียนแอปพลิเคชัน

เมื่อดำเนินการเสร็จแล้ว คุณจะเห็นหน้าเว็บที่มีคีย์ API ใหม่

1. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
2. แทนที่คีย์ API ในข้อมูลด้วยคีย์ที่ได้ด้านบน แล้วแก้ไขช่องอีเมล

การแก้ปัญหา

การทำงานกับ API ของบุคคลที่สามอาจเกิดข้อผิดพลาดได้หลายสาเหตุ เช่น

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

ในทุกกรณีเหล่านี้และกรณีอื่นๆ ขั้นตอนแรกที่ดีในการระบุสาเหตุของปัญหาคือการตรวจสอบรายละเอียดของการตอบกลับที่ทำให้เกิดข้อผิดพลาด

แยกวิเคราะห์คำตอบ

โดยค่าเริ่มต้น เครื่องยนต์สคริปต์ของ Google Ads จะแสดงข้อผิดพลาด (รหัสสถานะ 400 ขึ้นไป) ในการตอบกลับ

หากต้องการป้องกันลักษณะการทำงานนี้และอนุญาตให้ตรวจสอบข้อผิดพลาดและข้อความแสดงข้อผิดพลาด ให้ตั้งค่าพร็อพเพอร์ตี้ muteHttpExceptions ของพารามิเตอร์ที่ไม่บังคับเป็น UrlFetchApp.fetch เช่น

const params = {
  muteHttpExceptions: true
};
const response = UrlFetchApp.fetch(url, params);
if (response.getResponseCode() >= 400) {
  // ... inspect error details...
}

รหัสสถานะที่พบบ่อย

• 200 OK หมายถึง "สำเร็จ" หากคำตอบไม่มีข้อมูลที่คาดไว้ ให้พิจารณาดังนี้

  • API บางรายการอนุญาตให้ระบุช่องและ/หรือรูปแบบการตอบกลับที่จะใช้ โปรดดูรายละเอียดเกี่ยวกับเรื่องนี้ในเอกสารประกอบของ API
  • API อาจมีทรัพยากรหลายรายการที่เรียกใช้ได้ โปรดอ่านเอกสารประกอบเพื่อพิจารณาว่าควรใช้ทรัพยากรอื่นหรือไม่ และทรัพยากรนั้นสามารถแสดงข้อมูลที่คุณต้องการได้หรือไม่
  • API อาจเปลี่ยนแปลงไปตั้งแต่มีการเขียนโค้ด โปรดอ่านเอกสารประกอบหรือสอบถามนักพัฒนาแอปเพื่อขอคำชี้แจง

• 400 Bad Request โดยทั่วไปหมายความว่ามีบางอย่างไม่ถูกต้องในการจัดรูปแบบหรือโครงสร้างของคําขอที่ส่งไปยังเซิร์ฟเวอร์ ตรวจสอบคำขอและเปรียบเทียบกับข้อมูลจำเพาะของ API เพื่อให้แน่ใจว่าเป็นไปตามความคาดหวัง ดูรายละเอียดเกี่ยวกับวิธีตรวจสอบคำขอได้ที่การตรวจสอบคำขอ

• 401 Unauthorized มักหมายความว่ามีการเรียก API โดยไม่ระบุหรือดำเนินการให้สิทธิ์สำเร็จ

  • หาก API ใช้การให้สิทธิ์พื้นฐาน ให้ตรวจสอบว่าระบบสร้างและระบุส่วนหัว Authorization ในคำขอแล้ว
  • หาก API ใช้ OAuth 2.0 ให้ตรวจสอบว่าได้โทเค็นการเข้าถึงแล้ว และส่งเป็นโทเค็นสำหรับผู้ถือ
  • สำหรับการให้สิทธิ์รูปแบบอื่นๆ โปรดตรวจสอบว่าได้ระบุข้อมูลเข้าสู่ระบบที่จำเป็นสำหรับคำขอแล้ว

• 403 Forbidden บ่งบอกว่าผู้ใช้ไม่มีสิทธิ์สำหรับทรัพยากรที่ขอ

  • ตรวจสอบว่าผู้ใช้ได้รับสิทธิ์ที่จำเป็น เช่น ให้สิทธิ์ผู้ใช้เข้าถึงไฟล์ในคำขอตามไฟล์

• 404 Not Found หมายความว่าไม่มีทรัพยากรที่ขอ

  • ตรวจสอบว่า URL ที่ใช้สำหรับปลายทาง API ถูกต้อง
  • หากดึงข้อมูลทรัพยากร ให้ตรวจสอบว่าทรัพยากรที่อ้างอิงมีอยู่จริง (เช่น ไฟล์มีอยู่ใน API อิงตามไฟล์หรือไม่)

ตรวจสอบคำขอ

การตรวจสอบคำขอมีประโยชน์เมื่อการตอบกลับของ API ระบุว่าคำขอมีรูปแบบไม่ถูกต้อง เช่น รหัสสถานะ 400 UrlFetchApp มีเมธอดที่ทำงานร่วมกับเมธอด fetch() ชื่อว่า getRequest() เพื่อช่วยตรวจสอบคำขอ

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

ตัวอย่างเช่น หากข้อมูลแบบฟอร์มในคําขอประกอบด้วยสตริงหลายรายการที่ต่อต่อกัน ข้อผิดพลาดอาจอยู่ในฟังก์ชันที่คุณสร้างเพื่อสร้างข้อมูลแบบฟอร์มนั้น สรุปสั้นๆ

const request = UrlFetchApp.getRequest(url, params);
console.log(request);
// Now make the fetch:
const response = UrlFetchApp.fetch(url, params);
// ...

จะช่วยให้คุณตรวจสอบองค์ประกอบของคำขอได้

บันทึกคําขอและการตอบกลับ

หากต้องการความช่วยเหลือตลอดกระบวนการตรวจสอบคําขอและการตอบกลับ API ของบุคคลที่สาม ให้ใช้ฟังก์ชันตัวช่วยต่อไปนี้แทน UrlFetchApp.fetch() เพื่อบันทึกทั้งคําขอและการตอบกลับ

1. แทนที่อินสแตนซ์ทั้งหมดของ UrlFetchApp.fetch() ในโค้ดด้วย logUrlFetch()

2. เพิ่มฟังก์ชันต่อไปนี้ที่ส่วนท้ายของสคริปต์

   function logUrlFetch(url, opt_params) {
     const params = opt_params || {};
     params.muteHttpExceptions = true;
     const request = UrlFetchApp.getRequest(url, params);
     console.log('Request:       >>> ' + JSON.stringify(request));
     const response = UrlFetchApp.fetch(url, params);
     console.log('Response Code: <<< ' + response.getResponseCode());
     console.log('Response text: <<< ' + response.getContentText());
     if (response.getResponseCode() >= 400) {
       throw Error('Error in response: ' + response);
     }
     return response;
   }
   

เมื่อเรียกใช้สคริปต์ ระบบจะบันทึกรายละเอียดของคําขอและคําตอบทั้งหมดลงในคอนโซล ซึ่งช่วยให้แก้ไขข้อบกพร่องได้ง่ายขึ้น