กำหนดค่าแอปสำหรับ Ambient API

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

แอปพลิเคชันของคุณโต้ตอบกับ Ambient API ในนามของผู้ใช้ Ambient API ผู้ใช้ให้สิทธิ์คำขอ API เหล่านี้โดยใช้โปรโตคอล OAuth 2.0

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

กำหนดค่าแอป

ขั้นแรกให้เปิดใช้ API แล้วขอรหัสไคลเอ็นต์ OAuth 2.0

เปิดใช้ API

คุณต้องเปิดใช้ Ambient API ในโปรเจ็กต์ก่อนจึงจะใช้ได้

1. ไปที่คอนโซล Google API
2. จากแถบเมนู ให้เลือกโปรเจ็กต์หรือสร้างโปรเจ็กต์ใหม่
3. หากต้องการเปิด Google Photos API รายการใดรายการหนึ่ง จากเมนูการนำทาง ให้เลือกAPI และบริการ > ไลบรารี
4. ค้นหา "Ambient API" เลือก Ambient API แล้วคลิกเปิดใช้

ขอรหัสไคลเอ็นต์ OAuth 2.0

ทำตามขั้นตอนต่อไปนี้เพื่อขอรหัสไคลเอ็นต์ OAuth และกำหนดค่าสำหรับแอปพลิเคชัน Ambient API ใช้ OAuth 2.0 สําหรับแอปพลิเคชันทีวีและอุปกรณ์ที่มีอินพุตจํากัด

1. ไปที่คอนโซล Google API แล้วเลือกโปรเจ็กต์
2. จากเมนู ให้เลือก API และบริการ > ข้อมูลเข้าสู่ระบบ

3. ในหน้าข้อมูลเข้าสู่ระบบ ให้คลิกสร้างข้อมูลเข้าสู่ระบบ > รหัสไคลเอ็นต์ OAuth

   หมายเหตุ: หากกำลังตั้งค่าโปรเจ็กต์ใหม่ ระบบอาจแจ้งให้คุณกำหนดค่าหน้าจอความยินยอมของโปรเจ็กต์

4. เลือกประเภทแอปพลิเคชัน ในตัวอย่างนี้ ประเภทแอปพลิเคชันคือทีวีและอุปกรณ์อินพุตที่จำกัด

5. ระบุชื่อไคลเอ็นต์ OAuth 2.0 แล้วคลิกสร้าง

6. จากกล่องโต้ตอบไคลเอ็นต์ OAuth ที่ปรากฏขึ้น ให้คัดลอกข้อมูลต่อไปนี้

   • รหัสลูกค้า
   • รหัสลับไคลเอ็นต์

แอปของคุณจะเข้าถึง Google API ที่เปิดใช้ได้โดยใช้ค่าเหล่านี้

Google ต้องตรวจสอบแอปของคุณก่อนจึงจะเปิดตัวแอปพลิเคชันสาธารณะที่เข้าถึง Ambient API ได้ ข้อความ "แอปที่ยังไม่ยืนยัน" จะปรากฏบนหน้าจอเมื่อคุณทดสอบแอปพลิเคชันจนกว่าแอปจะได้รับการยืนยัน

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

• สร้างและจัดการอุปกรณ์
• แสดงรายการและเรียกข้อมูลรายการสื่อ

การเปลี่ยนรหัสไคลเอ็นต์

ทรัพยากรที่สร้างผ่าน Google Photos API ใดๆ จะเข้าถึงหรือแก้ไขได้โดยใช้รหัสไคลเอ็นต์เดิมที่ใช้สร้างเท่านั้น ตัวอย่างเช่น หากคุณสร้าง session ใน Picker API ด้วยรหัสไคลเอ็นต์ที่เฉพาะเจาะจง แล้วเปลี่ยนรหัสไคลเอ็นต์นั้นในแอปในภายหลัง แอปจะเสียสิทธิ์เข้าถึงทรัพยากร API ที่สร้างขึ้นด้วยรหัสไคลเอ็นต์ก่อนหน้า

วางแผนอย่างรอบคอบและเลือกประเภทรหัสไคลเอ็นต์ที่ถูกต้องสำหรับ Photos API ที่คุณใช้ เปลี่ยนรหัสไคลเอ็นต์เฉพาะในกรณีที่จําเป็นอย่างยิ่งเพื่อหลีกเลี่ยงปัญหาการเข้าถึง

ปรับปรุงขั้นตอนการตรวจสอบสิทธิ์สําหรับ Ambient API

ขั้นตอนการตรวจสอบสิทธิ์ Ambient API มาตรฐานกำหนดให้ผู้ใช้สแกนคิวอาร์โค้ด 2 รายการ ดังนี้

• ลงชื่อเข้าใช้บัญชี Google เป็นคนแรก (หากยังไม่ได้ลงชื่อเข้าใช้)
• บัญชีที่ 2 ซึ่งลิงก์กับอุปกรณ์ Ambient ที่สร้างขึ้นใหม่ในบัญชี Google Photos ของผู้ใช้ ซึ่งผู้ใช้สามารถเลือกรายการสื่อที่จะแสดงได้

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

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

พารามิเตอร์
requestId	string ต้องระบุ ตัวระบุที่ไม่ซ้ำกันซึ่งไคลเอ็นต์ระบุสำหรับคำขอนี้ ซึ่งใช้เพื่อลดการซ้ำซ้อนของทรัพยากรในกรณีที่เครือข่ายขัดข้อง รหัสนี้ต้องอยู่ในรูปแบบสตริง UUID (เวอร์ชัน 4) และเป็นไปตามข้อกําหนดต่อไปนี้ ต้องไม่มีข้อมูลที่ละเอียดอ่อนซึ่งระบุตัวตนของผู้ใช้ ประกอบด้วยอักขระฐานสิบหก 32 ตัวที่แบ่งออกเป็น 5 กลุ่มและคั่นด้วยเครื่องหมายขีดกลางในรูปแบบ "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (หรือ 8-4-4-4-12)
displayName	string ไม่บังคับ ชื่อที่แสดงที่ผู้ใช้กำหนดสำหรับอุปกรณ์นี้ ผู้ใช้จะเห็นการตั้งค่านี้จากการตั้งค่าแอป Google Photos แต่แก้ไขได้ผ่าน API นี้เท่านั้น ชื่อที่แสดงที่ถูกต้องต้องมีความยาวระหว่าง 1 ถึง 100 อักขระ (รวม)

ตัวอย่างเช่น โปรดดูบล็อกโค้ดต่อไปนี้

    const response = await fetch("https://oauth2.googleapis.com/device/code", {
        method: 'POST',
        headers: {
            'Content-Type': 'application/json',
        },
        body: JSON.stringify({
            client_id: config.clientId,
            scope: "profile https://www.googleapis.com/auth/photosambient.mediaitems",
            state: JSON.stringify({
                'requestId': requestId,
                'displayName': "My Device"
            })
        })
    });

การตอบกลับที่สำเร็จจะมี user_code และ verification_url ซึ่งคุณแสดงต่อผู้ใช้ (มักจะเป็นคิวอาร์โค้ด) เพื่อให้ผู้ใช้ไปยังส่วนนั้นในอุปกรณ์เครื่องอื่นได้ การใส่พารามิเตอร์ state ไว้จะช่วยให้คุณข้ามการแสดง settingsUri ในคิวอาร์โค้ดที่ 2 ได้เมื่อเรียกใช้ createDevice ด้วย Ambient API ในภายหลัง เนื่องจากขั้นตอนสุดท้ายในขั้นตอนการขอสิทธิ์ OAuth จะเปลี่ยนเส้นทางไปยังตำแหน่งนี้โดยอัตโนมัติ

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

รายละเอียดเกี่ยวกับขั้นตอนการตรวจสอบสิทธิ์ที่มีประสิทธิภาพมากขึ้น

หากต้องการทําความเข้าใจขั้นตอน OAuth ที่มีประสิทธิภาพมากขึ้นสําหรับ Ambient API อย่างถ่องแท้ คุณควรทําความเข้าใจทั้งขั้นตอน OAuth 2.0 สําหรับทีวีและแอปพลิเคชันอุปกรณ์ที่มีอินพุตจํากัด รวมถึงขั้นตอน Ambient API มาตรฐาน ขั้นตอนสำหรับแต่ละขั้นตอนมีดังนี้

OAuth 2.0 สำหรับแอปพลิเคชันทีวีและอุปกรณ์ที่มีอินพุตแบบจำกัด:

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

ขั้นตอนการเรียกใช้ Ambient API:

1. ตรวจสอบว่ามีโทเค็น OAuth อยู่หรือไม่ แล้วรีเฟรชโทเค็นหรือขอโทเค็นใหม่
2. หลังจากได้รับโทเค็น OAuth แล้ว ให้สร้างอุปกรณ์ใหม่
3. แสดง settingsUri ต่อผู้ใช้ แล้วเริ่มสำรวจอุปกรณ์จนกว่า mediaSourcesSet จะแสดงผลเป็น "จริง"
4. ผู้ใช้ไปยัง settingsUri แล้วเลือกรูปภาพที่ต้องการแชร์กับแอปพลิเคชัน
5. เมื่อ mediaSourcesSet แสดงผลเป็นจริง ให้ดึงข้อมูลรายการ mediaItems
6. ตอนนี้คุณก็เริ่มสไลด์โชว์หรือประสบการณ์การใช้งานแบบแอมเบียนท์อื่นๆ ได้แล้ว

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

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

โปรดคํานึงถึงประเด็นต่อไปนี้

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