หน้านี้ได้รับการแปลโดย Cloud Translation API

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

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

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

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

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

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

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

ตั้งค่า Slack

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

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

ตั้งค่าเว็บฮุคขาเข้าโดยคลิกเพิ่มการผสานรวม WebHooks ขาเข้า แล้วทำตามวิธีการ ขั้นตอนนี้ควรมี URL เพื่อใช้ในการรับส่งข้อความ

ส่งคำขอ POST

เมื่อตั้งค่าเว็บฮุคขาเข้าแล้ว การสร้างคำขอ 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: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
ระบบจะแปลงคู่คีย์/ค่าเป็น form-data ดังนี้
```
subject=Test&to=mail@example.com&body=Hello,+World!
```
และตั้งค่าส่วนหัว Content-Type ของคําขอเป็น application/x-www-form-urlencoded ด้วย

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

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

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

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

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

สร้างคำขอ

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

สร้างรหัสผ่านโดยการรวมชื่อผู้ใช้และรหัสผ่านเข้าด้วยกันด้วยโคลอน เช่น username:password
Base64 เข้ารหัสรหัสผ่าน เช่น username:password จะกลายเป็น dXNlcm5hbWU6cGFzc3dvcmQ=
แนบส่วนหัว 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);

Plivo

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

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

Twilio

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

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

OAuth 1.0

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

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

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

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

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

OAuth1

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

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

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

OAuth 2.0

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

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

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

นอกสคริปต์ของคุณ

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

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

ในสคริปต์ของคุณ

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

สร้างคำขอ 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);

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

การให้สิทธิ์ข้อมูลเข้าสู่ระบบไคลเอ็นต์เป็นรูปแบบหนึ่งของโฟลว์ 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 มี UI ที่อนุญาตให้ผู้ใช้ทำตามขั้นตอนการให้สิทธิ์รหัสการให้สิทธิ์เพื่อรับโทเค็นการรีเฟรช

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

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

สนามเด็กเล่น 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 เพื่อดูรายละเอียดทั้งหมดเกี่ยวกับการดำเนินการอื่นๆ ที่สามารถทำได้

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

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

ตัวอย่าง 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 เพื่อการดำเนินการ

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

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

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

บัญชีบริการ

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

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

ตัวอย่าง API ภาษาธรรมชาติของ Google

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

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

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

สร้างโปรเจ็กต์ใหม่ในคอนโซล API
เปิดใช้ Natural Language API
เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์
สร้างบัญชีบริการ ดาวน์โหลดไฟล์ JSON ของข้อมูลเข้าสู่ระบบ
วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
นอกจากนี้ ให้วางตัวอย่างไลบรารี OAuth2 ใต้รายการโค้ด
แทนที่ค่าที่จําเป็นต่อไปนี้
- serviceAccount: อีเมลของบัญชีบริการ เช่น xxxxx@yyyy.iam.gserviceaccount.com
- 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

ไปที่เว็บไซต์ของนักพัฒนาซอฟต์แวร์ Sportsradar
ลงทะเบียนบัญชีทดลองใช้
หลังจากลงทะเบียนแล้ว ให้ลงชื่อเข้าใช้บัญชีของคุณ
เมื่อเข้าสู่ระบบแล้วให้ไปที่MyAccount

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

ในส่วนแอปพลิเคชัน ให้คลิก Create a new Application (สร้างแอปพลิเคชันใหม่) ตั้งชื่อและใส่คำอธิบาย ให้แอปพลิเคชัน ไม่ต้องสนใจช่องเว็บไซต์
เลือกเฉพาะออกคีย์ใหม่สำหรับ Soccer Trial Europe v2 เท่านั้น
คลิกลงทะเบียนแอปพลิเคชัน

เมื่อยืนยันสำเร็จ ควรจะเห็นหน้าเว็บที่มีคีย์ API ใหม่ของคุณอยู่

วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
แทนที่คีย์ 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);
// ...

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

บันทึกคำขอและคำตอบ

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

แทนที่ UrlFetchApp.fetch() ทั้งหมดในโค้ดด้วย logUrlFetch()

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

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

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