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

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

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

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

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

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

ดึงข้อมูลด้วย 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 CANNOT TRANSLATE ตัวอย่างแบบขยายจะแสดงให้เห็นถึง การสร้างและการส่งประสิทธิภาพของแคมเปญ รายงานไปยัง รวมถึงตัวเลือกการจัดรูปแบบและการแสดงผลบางอย่าง

ข้อความขาเข้า

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

ข้อมูลฟอร์ม

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

UrlFetchApp ใช้วิธีการที่แตกต่างกัน ทั้งนี้ขึ้นอยู่กับรูปแบบของ payload เพื่อสร้างคำขอ POST:

เมื่อ payload เป็นสตริง ระบบจะส่งอาร์กิวเมนต์สตริงเป็น เนื้อหาของคำขอ
เช่น เมื่อ payload เป็นออบเจ็กต์ ตัวอย่างการแมปค่ามีดังนี้
```
{to: 'mail@example.com', subject:'Test', body:'Hello, World!'}
```
คู่คีย์/ค่าจะแปลงเป็นข้อมูลแบบฟอร์ม
```
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);

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

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

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 ด้วยหมายเลขจาก dashboard--นี่คือ หมายเลขที่ Twilio ให้สิทธิ์ส่งข้อความ

OAuth 1.0

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

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

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

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

สำหรับบริการของบุคคลที่สามให้ใช้ 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 Script ควรเป็น และโดยปกติแล้วจะได้รับการกำหนดรหัสไคลเอ็นต์ ซึ่งช่วยให้คุณผ่านทาง 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

การให้สิทธิ์โทเค็นการรีเฟรช

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

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

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

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

รหัสการให้สิทธิ์

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

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

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

ตัวอย่าง API การสั่งการ Apps Script

ตัวอย่างนี้แสดงการเรียกใช้ฟังก์ชันใน 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 ที่เหมาะสม ซึ่งในกรณีนี้คือไดรฟ์ API และApps การรันสคริปต์ API
สร้างข้อมูลเข้าสู่ระบบ OAuth จากรายการข้อมูลเข้าสู่ระบบในเมนู
กลับไปที่สคริปต์ ให้เผยแพร่สคริปต์เพื่อเรียกใช้งานจาก เผยแพร่ > ทำให้ใช้งานได้เป็นไฟล์ดำเนินการของ API

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

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

บัญชีบริการ

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

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

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

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

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

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

สร้างโปรเจ็กต์ใหม่ในคอนโซล API
เปิดใช้ภาษาธรรมชาติ API
เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์
สร้างบริการ บัญชี ดาวน์โหลดไฟล์ JSON ของข้อมูลเข้าสู่ระบบ
วางตัวอย่าง ลงในไฟล์ ใน Google Ads
นอกจากนี้ ให้วาง OAuth2 ตัวอย่าง Library ภายใต้ รายการรหัส
แทนที่ค่าที่��ำเป็น ดังนี้
- 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 ชิ้น แอปพลิเคชันที่คุณสร้างสามารถเชื่อมโยงกับกีฬาที่แตกต่างกันได้ และ คีย์ต่างๆ

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

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

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

การแก้ปัญหา

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

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

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

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

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

หากต้องการป้องกันการทำงานลักษณะนี้ และเพื่อให้ข้อผิดพลาดและข้อความแสดงข้อผิดพลาด ตรวจสอบแล้ว ให้ตั้งค่าพร็อพเพอร์ตี้ 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() เพื่อบันทึกทั้งคำขอและการตอบกลับ

แทนที่ 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;
}

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