Core Reporting API - การให้สิทธิ์

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

การให้สิทธิ์คำขอ

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

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

เกี่ยวกับโปรโตคอลการให้สิทธิ์

แอปพลิเคชันต้องใช้ OAuth 2.0 เพื่อให้สิทธิ์คำขอ ระบบไม่รองรับโปรโตคอลการให้สิทธิ์อื่นๆ หากแอปพลิเคชันใช้ลงชื่อเข้าใช้ด้วย Google ระบบจะจัดการการให้สิทธิ์บางส่วนแก่คุณ

การให้สิทธิ์คำขอด้วย OAuth 2.0

คำขอทั้งหมดที่ส่งไปยัง API ของ Analytics ต้องได้รับอนุญาตจากผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว

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

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

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

ข้อมูลขอบเขตของ OAuth 2.0 สําหรับ Analytics API มีดังนี้

ขอบเขต ความหมาย
https://www.googleapis.com/auth/analytics.readonly สิทธิ์การอ่านอย่างเดียวสำหรับ Analytics API

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

เคล็ดลับ: ไลบรารีของไคลเอ็นต์ Google APIs จัดการขั้นตอนการให้สิทธิ์บางส่วนให้คุณได้ ไลบรารีเหล่านี้พร้อมให้บริการเป็นภาษาโปรแกรมต่างๆ โปรดดูรายละเอียดเพิ่มเติมที่หน้าที่มีไลบรารีและตัวอย่าง

ขั้นตอนทั่วไปของ OAuth 2.0

กรณีการใช้งานทั่วไปของขั้นตอน OAuth 2.0 ที่เจาะจงมีดังต่อไปนี้

เว็บเซิร์ฟเวอร์

ขั้นตอนนี้เหมาะสำหรับการเข้าถึงข้อมูล Google Analytics ของผู้ใช้แบบอัตโนมัติ แบบออฟไลน์ หรือตามกำหนดเวลา

ตัวอย่าง

  • อัปเดตหน้าแดชบอร์ดผู้ใช้โดยอัตโนมัติด้วยข้อมูล Google Analytics ล่าสุด

ฝั่งไคลเอ็นต์

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

ตัวอย่าง

แอปพลิเคชันที่ติดตั้ง

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

ตัวอย่าง

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

บัญชีบริการ

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

หากต้องการเริ่มต้นใช้งาน Analytics API ก่อนอื่นคุณต้องใช้เครื่องมือตั้งค่า ซึ่งจะแนะนำขั้นตอนการสร้างโปรเจ็กต์ในคอนโซล Google API การเปิดใช้ API และสร้างข้อมูลเข้าสู่ระบบ

หากต้องการตั้งค่าบัญชีบริการใหม่ ให้ทำดังนี้

  1. คลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์บัญชีบริการ
  2. เลือกว่าจะดาวน์โหลดคีย์สาธารณะ/ส่วนตัวของบัญชีบริการเป็นไฟล์ P12 มาตรฐาน หรือเป็นไฟล์ JSON ที่โหลดโดยไลบรารีของไคลเอ็นต์ Google API ได้

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

การแก้ปัญหา

การให้สิทธิ์จะไม่สำเร็จในสถานการณ์ต่อไปนี้

  • คุณจะได้รับรหัสสถานะ 401 หาก access_token หมดอายุหรือคุณกำลังใช้ขอบเขตที่ไม่ถูกต้องสำหรับ API

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

สนามเด็กเล่น OAuth 2.0

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

การให้สิทธิ์ไม่ถูกต้อง

เมื่อพยายามใช้โทเค็นการรีเฟรช ข้อผิดพลาด invalid_grant จะแสดงผลดังนี้

แอปพลิเคชันสามารถขอโทเค็นการรีเฟรชหลายรายการเพื่อเข้าถึงบัญชี Google Analytics บัญชีเดียว

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

ขีดจำกัดสำหรับแต่ละคู่ที่ไม่ซ้ำกันของไคลเอ็นต์ OAuth 2.0 และบัญชี Google Analytics คือโทเค็นการรีเฟรช 25 รายการ หากแอปพลิเคชันยังคงขอโทเค็นการรีเฟรชสำหรับคู่ไคลเอ็นต์/บัญชีเดียวกัน เมื่อมีการออกโทเค็นรายการที่ 26 แล้ว โทเค็นการรีเฟรชรายการที่ 1 ที่ออกก่อนหน้านี้จะไม่สามารถใช้ได้ โทเค็นการรีเฟรชที่ขอครั้งที่ 27 จะทำให้โทเค็นที่ออกก่อนหน้านี้ฉบับที่ 2 ไม่ถูกต้อง และเป็นเช่นนี้ต่อไปเรื่อยๆ