คู่มือนี้อธิบายวิธีที่แอปพลิเคชันให้สิทธิ์คำขอไปยัง Real Time Reporting API
การให้สิทธิ์คำขอ
ผู้ใช้ต้องเข้าสู่ระบบบัญชี Google ของตนก่อน จึงจะดูข้อมูลบัญชีในเว็บไซต์ Google Analytics ได้ ในทำนองเดียวกัน เมื่อผู้ใช้เข้าถึงแอปพลิเคชันของคุณเป็นครั้งแรก ก็จะต้องให้สิทธิ์แอปพลิเคชันในการเข้าถึงข้อมูลของตน
ทุกคำขอที่แอปพลิเคชันส่งไปยัง Analytics API ต้องมีโทเค็นการให้สิทธิ์ โทเค็นดังกล่าวจะระบุตัวตนแอปพลิเคชันของคุณให้ Google ทราบด้วย
เกี่ยวกับโปรโตคอลการให้สิทธิ์
แอปพลิเคชันต้องใช้ OAuth 2.0 เพื่อให้สิทธิ์คำขอ ระบบไม่รองรับโปรโตคอลการให้สิทธิ์อื่นๆ หากแอปพลิเคชันใช้ลงชื่อเข้าใช้ด้วย Google ระบบจะจัดการการให้สิทธิ์บางส่วนแก่คุณ
การให้สิทธิ์คำขอด้วย OAuth 2.0
คำขอทั้งหมดที่ส่งไปยัง Analytics API จะต้องได้รับอนุญาตจากผู้ใช้ที่ตรวจสอบสิทธิ์แล้ว
รายละเอียดของกระบวนการให้สิทธิ์หรือ "ขั้นตอน" ของ OAuth 2.0 จะแตกต่างกันไปโดยขึ้นอยู่กับประเภทของแอปพลิเคชันที่คุณเขียน แอปพลิเคชันทุกประเภทจะใช้กระบวนการทั่วไปต่อไปนี้
- เมื่อสร้างแอปพลิเคชัน คุณจะลงทะเบียนแอปได้โดยใช้คอนโซล Google API จากนั้น Google จะให้ข้อมูลที่คุณต้องใช้ในภายหลัง เช่น รหัสไคลเอ็นต์และรหัสลับไคลเอ็นต์
- เปิดใช้งาน Analytics API ในคอนโซล Google API (หากไม่เห็น API ดังกล่าวในคอนโซล API ให้ข้ามขั้นตอนนี้ไป)
- เมื่อแอปพลิเคชันต้องการเข้าถึงข้อมูลผู้ใช้ แอปจะขอขอบเขตการเข้าถึงที่จำเป็นจาก Google
- Google จะแสดงหน้าจอขอคำยินยอมแก่ผู้ใช้เพื่อขอให้ผู้ใช้ให้สิทธิ์แอปพลิเคชันของคุณในการขอข้อมูลบางอย่างของผู้ใช้
- หากผู้ใช้อนุมัติ Google จะให้โทเค็นเพื่อการเข้าถึงที่มีอายุชั่วคราวแก่แอปพลิเคชันของคุณ
- แอปพลิเคชันขอข้อมูลผู้ใช้โดยแนบโทเค็นเพื่อการเข้าถึงไปกับคำขอ
- หาก 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 ภายในเบราว์เซอร์ ทำให้ไม่จำเป็นต้องใช้ความสามารถฝั่งเซิร์ฟเวอร์ แต่ทำให้การรายงานอัตโนมัติ ออฟไลน์ หรือตามกำหนดการทำงานไม่ได้จริง
ตัวอย่าง
- เครื่องมือการรายงานที่ใช้เบราว์เซอร์ เช่น Analytics Query Explorer
แอปพลิเคชันที่ติดตั้ง
ขั้นตอนนี้มีให้สำหรับแอปพลิเคชันที่เผยแพร่เป็นแพ็กเกจและผู้ใช้ติดตั้ง ขั้นตอนนี้กำหนดให้แอปพลิเคชันหรือผู้ใช้ต้องมีสิทธิ์เข้าถึงเบราว์เซอร์เพื่อทำตามขั้นตอนการตรวจสอบสิทธิ์ให้เสร็จสมบูรณ์
ตัวอย่าง
- วิดเจ็ตบนเดสก์ท็อปบน PC หรือ Mac
- ปลั๊กอินสำหรับระบบจัดการเนื้อหา — ประโยชน์ของขั้นตอนนี้เมื่อเทียบกับเว็บเซิร์ฟเวอร์หรือฝั่งไคลเอ็นต์คือ ใช้งานโปรเจ็กต์คอนโซล API เดียวสำหรับแอปพลิเคชันของคุณได้ ซึ่งจะช่วยให้ผู้ใช้ได้รับการรายงานรวมและติดตั้งได้ง่ายขึ้น
บัญชีบริการ
บัญชีบริการมีประโยชน์สำหรับการเข้าถึงข้อมูล Google Analytics แบบอัตโนมัติ ออฟไลน์ หรือตามกำหนดการในบัญชีของคุณเอง เช่น เพื่อสร้างหน้าแดชบอร์ดสดจากข้อมูล Google Analytics ของคุณเองและแชร์กับผู้ใช้คนอื่นๆ
หากต้องการเริ่มต้นใช้งาน Analytics API ก่อนอื่นคุณต้องใช้เครื่องมือตั้งค่า ซึ่งจะแนะนำขั้นตอนการสร้างโปรเจ็กต์ในคอนโซล Google API เปิดใช้ API และการสร้างข้อมูลเข้าสู่ระบบ
หากต้องการตั้งค่าบัญชีบริการใหม่ ให้ทำดังนี้
- คลิกสร้างข้อมูลเข้าสู่ระบบ > คีย์บัญชีบริการ
- เลือกว่าจะดาวน์โหลดคีย์สาธารณะ/ส่วนตัวของบัญชีบริการเป็นไฟล์ P12 มาตรฐาน หรือเป็นไฟล์ JSON ที่โหลดโดยไลบรารีของไคลเอ็นต์ Google API ได้
จะมีการสร้างคู่คีย์สาธารณะ/ส่วนตัวใหม่และดาวน์โหลดลงในเครื่องของคุณ โดยจะเป็นสำเนาเพียงรายการเดียวของคีย์นี้ คุณมีหน้าที่รับผิดชอบในการจัดเก็บ ให้ปลอดภัย
การแก้ปัญหา
การให้สิทธิ์จะไม่สำเร็จในสถานการณ์ต่อไปนี้
คุณจะได้รับรหัสสถานะ
401หากaccess_tokenหมดอายุหรือคุณใช้ขอบเขตที่ไม่ถูกต้องสำหรับ APIคุณจะได้รับรหัสสถานะ
403หากผู้ใช้ที่ได้รับอนุญาตไม่มีสิทธิ์เข้าถึงข้อมูลพร็อพเพอร์ตี้ (โปรไฟล์) โปรดตรวจสอบให้แน่ใจว่าคุณได้รับสิทธิ์ด้วยผู้ใช้ที่ถูกต้อง และผู้ใช้รายนั้นมีข้อมูลพร็อพเพอร์ตี้ (โปรไฟล์) ที่คุณเลือกไว้จริงๆ
สนามเด็กเล่น OAuth 2.0
เครื่องมือนี้จะช่วยให้คุณดำเนินการขั้นตอนการให้สิทธิ์ทั้งหมดผ่านเว็บอินเทอร์เฟซได้ นอกจากนี้ เครื่องมือจะแสดงส่วนหัวของคำขอ HTTP ทั้งหมดที่จำเป็นสำหรับการสร้างคำค้นหาที่ได้รับอนุญาต หากรับการให้สิทธิ์เพื่อทำงานในแอปพลิเคชันของคุณเองไม่ได้ คุณควรพยายามทำให้การให้สิทธิ์ใช้งานได้ผ่าน OAuth 2.0 จากนั้นคุณสามารถเปรียบเทียบส่วนหัว HTTP และคำขอจากสนามเด็กเล่นกับสิ่งที่แอปพลิเคชันส่งไปยัง Google Analytics ได้ การตรวจสอบนี้เป็นเพียงวิธีง่ายๆ ในการตรวจสอบว่าคุณจัดรูปแบบคำขออย่างถูกต้อง
การให้สิทธิ์ไม่ถูกต้อง
เมื่อพยายามใช้โทเค็นการรีเฟรช ข้อความแสดงข้อผิดพลาดต่อไปนี้จะแสดงข้อผิดพลาด invalid_grant
- นาฬิกาของเซิร์ฟเวอร์ไม่ซิงค์กับโปรโตคอลเวลาเครือข่าย - NTP
- โทเค็นการรีเฟรชเกินขีดจำกัด
แอปพลิเคชันสามารถขอโทเค็นการรีเฟรชหลายรายการเพื่อเข้าถึงบัญชี Google Analytics บัญชีเดียวได้
เช่น หากผู้ใช้ต้องการติดตั้งแอปพลิเคชันบนเครื่องหลายเครื่องและเข้าถึงบัญชี Google Analytics เดียวกัน ก็จะต้องมีโทเค็นแยกกันสำหรับแต่ละเครื่อง เมื่อโทเค็นการรีเฟรชมีจํานวนเกินขีดจำกัด โทเค็นเก่าจะใช้งานไม่ได้ ถ้าแอปพลิเคชันพยายามใช้โทเค็นการรีเฟรชที่ใช้งานไม่ได้ ระบบจะแสดงผลการตอบกลับข้อผิดพลาด invalid_grant
ขีดจํากัดสําหรับไคลเอ็นต์ OAuth 2.0 ที่ไม่ซ้ำกันแต่ละคู่และบัญชี Google Analytics คือโทเค็นการรีเฟรช 25 โทเค็น หากแอปพลิเคชันยังคงขอโทเค็นการรีเฟรชสำหรับคู่ไคลเอ็นต์/บัญชีเดียวกัน เมื่อออกโทเค็นรายการที่ 26 แล้ว โทเค็นการรีเฟรชที่ 1 ที่ออกให้ก่อนหน้านี้จะใช้ไม่ได้ โทเค็นการรีเฟรชที่ขอไปครั้งที่ 27 จะทำให้โทเค็นที่ออกก่อนหน้านี้ครั้งที่ 2 ไม่ถูกต้อง และเป็นเช่นนี้ไปเรื่อยๆ