ضبط تطبيقك لاستخدام واجهة برمجة التطبيقات Ambient API

لبدء استخدام Ambient API، عليك ضبط إعدادات مشروعك من خلال تفعيل واجهة برمجة التطبيقات في وحدة تحكّم Google API وإعداد معرّف عميل OAuth 2.0. تستخدم Ambient API بروتوكول OAuth 2.0 لتطبيقات التلفزيون والأجهزة التي تتضمّن إمكانيات إدخال محدودة.

يتفاعل تطبيقك مع Ambient API نيابةً عن مستخدم Ambient API. ويفوّض المستخدم طلبات واجهة برمجة التطبيقات هذه باستخدام بروتوكول OAuth 2.0.

يسمح معرِّف عميل OAuth 2.0 لمستخدمي تطبيقك بتسجيل الدخول والمصادقة وبالتالي استخدام Ambient API. لا تتوافق Ambient API مع حسابات الخدمة، ولاستخدام واجهات برمجة التطبيقات هذه، يجب أن يكون المستخدمون مسجّلين الدخول إلى حساب Google صالح.

ضبط إعدادات تطبيقك

فعِّل أولاً واجهة برمجة التطبيقات، ثم اطلب الحصول على معرّف عميل OAuth 2.0.

تفعيل واجهة برمجة التطبيقات

قبل أن تتمكّن من استخدام Ambient API، عليك تفعيلها في مشروعك.

1. انتقِل إلى وحدة تحكّم واجهة برمجة التطبيقات Google API.
2. من شريط القوائم، اختَر مشروعًا أو أنشئ مشروعًا جديدًا.
3. لفتح إحدى واجهات برمجة التطبيقات في "صور Google"، اختَر واجهات برمجة التطبيقات والخدمات > المكتبة من قائمة "التنقّل".
4. ابحث عن Ambient API. اختَر Ambient API وانقر على تفعيل.

طلب معرّف عميل OAuth 2.0

اتّبِع الخطوات التالية لطلب معرّف عميل OAuth وضبطه لتطبيقك. تستخدم Ambient API بروتوكول OAuth 2.0 لتطبيقات التلفزيون وتطبيقات الأجهزة التي تتضمّن عددًا محدودًا من عناصر التحكم.

1. انتقِل إلى وحدة تحكّم واجهة برمجة تطبيقات Google واختَر مشروعك.
2. من القائمة، اختَر واجهات برمجة التطبيقات والخدمات > بيانات الاعتماد.

3. في صفحة بيانات الاعتماد، انقر على إنشاء بيانات اعتماد > معرِّف عميل OAuth.

   ملاحظة: إذا كنت بصدد إعداد مشروع جديد، قد يُطلب منك ضبط شاشة الموافقة في مشروعك.

4. اختَر نوع التطبيق. في هذا المثال، يكون نوع التطبيق هو أجهزة التلفزيون والأجهزة التي تتطلّب إدخال بيانات محدودة.

5. أدخِل اسمًا لعميل OAuth 2.0 وانقر على إنشاء.

6. من مربّع حوار عميل OAuth الناتج، انسخ ما يلي:

   • معرِّف العميل
   • سر العميل

يمكن لتطبيقك الوصول إلى واجهات برمجة تطبيقات Google المفعَّلة باستخدام هذه القيم.

قبل أن تتمكّن من إطلاق تطبيق متاح للجميع يمكنه الوصول إلى واجهة برمجة التطبيقات Ambient API، يجب أن تراجع Google تطبيقك. تظهر رسالة "التطبيق لم يتم إثبات ملكيته" على الشاشة عند اختبار تطبيقك إلى أن يتم إثبات ملكيته.

بعد ضبط إعدادات تطبيقك، ستكون مستعدًا للبدء. يمكنك الاطّلاع على المراجع التالية، أو الاطّلاع على مزيد من المعلومات عن مسار المصادقة المبسّط لواجهة برمجة التطبيقات Ambient API.

• إنشاء الأجهزة وإدارتها
• عرض عناصر الوسائط واستعادتها

تغيير معرّف العميل

لا يمكن الوصول إلى الموارد التي تم إنشاؤها من خلال أي من واجهات برمجة تطبيقات "صور Google" أو تعديلها إلا باستخدام معرّف العميل الأصلي المستخدَم لإنشائها. على سبيل المثال، إذا أنشأت session في Picker API باستخدام معرِّف عميل محدّد وغيّرت لاحقًا معرِّف العميل هذا في تطبيقك، سيفقد تطبيقك إمكانية الوصول إلى أي موارد لواجهة برمجة التطبيقات تم إنشاؤها باستخدام معرِّف العميل السابق.

خطط بعناية واختَر نوع رقم تعريف العميل الصحيح لواجهة برمجة التطبيقات Photos API التي تستخدمها. لا تغيِّر رقم تعريف العميل إلا إذا كان ذلك ضروريًا تمامًا لتجنُّب مشاكل تتعلّق بالوصول.

مسار مصادقة مبسّط لواجهة برمجة التطبيقات Ambient API

تتطلّب عملية المصادقة العادية في Ambient API من المستخدمين مسح رمزَي رمز الاستجابة السريعة:

• يجب أن يسجّل المستخدم الأول الدخول إلى حسابه على Google (إذا لم يكن مسجّلاً الدخول سابقًا).
• رابط ثانٍ ينقل إلى جهاز Ambient الذي تم إنشاؤه حديثًا في حسابهم على "صور Google" حيث يمكنهم اختيار عناصر الوسائط المراد عرضها

يتيح لك المسار المبسّط تقديم رمز استجابة سريعة واحد إلى المستخدمين من خلال تمرير المَعلمة state الإضافية مع طلب المصادقة الأوّلي.

عند طلب رموز الأجهزة والمستخدمين كجزء من OAuth لأجهزة الإدخال المحدود، أدرِج المَعلمة state الإضافية مع طلبك. أضِف ما يلي إلى المَعلمة state:

المعلمات
requestId	string مطلوب. معرّف فريد يقدّمه العميل لهذا الطلب. يُستخدَم ذلك للحدّ من تكرار الموارد في حال تعذّر الاتصال بالشبكة. يجب أن يكون رقم التعريف هذا بتنسيق سلسلة UUID (الإصدار 4) وأن يستوفي المتطلبات التالية: يجب ألا يحتوي على أي معلومات حسّاسة تحدّد هوية المستخدم. يجب أن يحتوي على 32 حرفًا سداسيًا عشريًا مقسمة إلى خمس مجموعات مفصولة بشرطات، بالتنسيق التالي: "xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx" (أو 8-4-4-4-12).
displayName	string اختياريّ. اسم معروض يحدّده المستخدم لهذا الجهاز. سيظهر هذا الخيار للمستخدمين من إعدادات تطبيق "صور Google"، ولكن لا يمكن تعديله إلا من خلال واجهة برمجة التطبيقات هذه. يجب أن يتألّف الاسم المعروض الصالح من بين حرف واحد و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، يمكنك عند طلب createDevice لاحقًا باستخدام Ambient API، تخطّي عرضsettingsUri في رمز استجابة سريعة ثانٍ، لأنّ الخطوة الأخيرة في عملية 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. يمكنك الآن بدء عرض الشرائح أو تجربة شاشة الاستراحة الأخرى.

تتضمّن كلتا المخطّطَين خطوة تعرض فيها عنوان URL للمستخدم، ويقوم المستخدم بدوره بالانتقال إلى ذلك العنوان على جهاز الإدخال المزوّد بميزات إضافية. من خلال تضمين المَعلمة state في طلب OAuth الأوّلي، يمكنك تجنُّب عنوان URL الثاني الذي عليك عرضه.

ويعود سبب ذلك إلى أنّ الخطوة الأخيرة من عملية OAuth 2.0 لتطبيقات الأجهزة المزوّدة بشاشة تلفزيون وأجهزة الإدخال المحدود تعيد توجيه المستخدم عادةً إلى صفحة تعرض الرسالة "يمكنك الآن العودة إلى جهازك". من خلال تضمين مَعلمة الحالة، ستحاول الخطوة الأخيرة من العملية الآن إعادة توجيهك إلى settingsUri. سيظلّ تطبيقك يتلقّى رمز OAuth. يجب استخدام هذا الرمز المميّز للاتصال بخدمة createDevice باستخدام requestId نفسه. بعد إنشاء جهاز يحمل المعرّف نفسه، ستعيد عملية OAuth الأولية توجيه المستخدم بنجاح إلى الصفحة الصحيحة على الجهاز المزوّد بميزات متقدمة في تطبيق "صور Google".

يُرجى مراعاة النقاط التالية:

• يُعدّ عرض الرمز settingsUri فكرة جيدة في حال حدوث أي مشاكل في المصادقة.
• سيظل بإمكانك استخدام الرمز settingsUri في حالات أخرى، مثل عندما يريد مستخدم تعديل اختيار الصور.