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

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

ตั้งค่า Slack

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

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

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

ส่งคำขอ POST

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

  • method: ดังที่กล่าวไว้ ค่าเริ่มต้นของตัวเลือกนี้คือ GET แต่ในที่นี้เราจะลบล้างและตั้งค่าเป็น POST
  • payload: ข้อมูลนี้จะส่งไปยังเซิร์ฟเวอร์โดยเป็นส่วนหนึ่งของคำขอ POST ในตัวอย่างนี้ Slack คาดหวังออบเจ็กต์ที่แปลงเป็นรูปแบบ JSON ตามที่อธิบายไว้ในเอกสารประกอบของ Slack โดยจะใช้เมธอด [JSON.stringify][json-stringify-url] และตั้งค่า 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!'}
    

    ระบบจะแปลงคู่คีย์-ค่าเป็นข้อมูลแบบฟอร์ม ดังนี้

    subject=Test&to=mail@example.com&body=Hello,+World!
    

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

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

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

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

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

การตรวจสอบสิทธิ์พื้นฐานของ 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 ดังนี้

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 โดยเฉพาะอย่างยิ่ง โปรดดู6. การตรวจสอบสิทธิ์ด้วย OAuth ใน OAuth 1.0 แบบ 3 ทางเต็มรูปแบบ กระบวนการจะเป็นดังนี้

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

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

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

ในสคริปต์

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

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

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

[การให้สิทธิ์ข้อมูลเข้าสู่ระบบไคลเอ็นต์][client-credentials-rfc] เป็นหนึ่งในรูปแบบที่ง่ายกว่าของขั้นตอน 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

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

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

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

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

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

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

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

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

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

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

    OAuth Playground

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

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

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

ตัวอย่าง Search Ads 360

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

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

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

บัญชีบริการ

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

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

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

[Natural Language API][natural-language-api-docs] มี[การวิเคราะห์ความเห็น][sentiment-analysis-api-docs] และ[การวิเคราะห์เอนทิตี][entity-analysis-api-docs] สำหรับข้อความ

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

ตั้งค่าสคริปต์
  1. สร้างโปรเจ็กต์ใหม่ในคอนโซล Google Cloud
  2. เปิดใช้ [Natural Language API][natural-language-api]
  3. เปิดใช้การเรียกเก็บเงินสำหรับโปรเจ็กต์
  4. [สร้างบัญชีบริการ][create-service-account] ดาวน์โหลดไฟล์ JSON ของข้อมูลเข้าสู่ระบบ
  5. วาง[สคริปต์ตัวอย่าง][natural-language-example] ลงในสคริปต์ใหม่ใน Google Ads
  6. นอกจากนี้ ให้วาง [ไลบรารี OAuth2 ตัวอย่าง][oauth20-library-example] ไว้ใต้รายการโค้ด
  7. แทนที่ค่าที่จำเป็นดังนี้
    • 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

XmlService ช่วยให้สคริปต์แยกวิเคราะห์และดึงข้อมูลจากเนื้อหาการตอบกลับ 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_schedules xmlns="http://schemas.sportradar.com/sportsapi/soccer/v4">
  <schedule>
     ...
  </schedule>
</schedule_schedules>

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

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

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

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

รับค่า

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

<sport_event_status status="..." ... />

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

const statusElement = sportEventElement.getChild('sport_event_status', namespace);
const status = statusElement.getAttribute('status').getValue();

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

ตัวอย่าง Sportradar

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

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

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

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

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

  1. วางสคริปต์ตัวอย่างลงในสคริปต์ใหม่ใน Google Ads
  2. แทนที่คีย์ 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 บางรายการอนุญาตให้ระบุช่อง รูปแบบการตอบกลับ หรือทั้ง 2 อย่างที่จะใช้ โปรดดูรายละเอียดเกี่ยวกับเรื่องนี้ในเอกสารประกอบเกี่ยวกับ 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(url, params) เพื่อช่วยตรวจสอบคำขอ

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

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

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

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

[json-stringify-url]: //developer.mozilla.org/en/docs/Web/JavaScript/Reference/Global_Objects/JSON/stringify [client-credentials-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-4.4 [authorization-code-rfc]: //datatracker.ietf.org/doc/html/rfc6749#section-1.3.1 [oauth20-library-example]: /google-ads/scripts/docs/examples/oauth20-library [search-ads-360-example]: /google-ads/scripts/docs/examples/search-ads-360 [natural-language-api]: //console.developers.google.com/apis/api/language.googleapis.com/overview [create-service-account]: //console.developers.google.com/apis/credentials/serviceaccountkey [natural-language-example]: /google-ads/scripts/docs/examples/natural-language [natural-language-api-docs]: //cloud.google.com/natural-language/docs/ [sentiment-api-docs]: //cloud.google.com/natural-language/docs/reference/rest/v1beta2/Sentiment [sentiment-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-sentiment [entity-analysis-api-docs]: //cloud.google.com/natural-language/docs/analyzing-entities