برنامه خود را برای Ambient API پیکربندی کنید

برای شروع استفاده از Ambient API، پروژه خود را با فعال کردن api در Google API Console و تنظیم شناسه مشتری OAuth 2.0 پیکربندی کنید. Ambient API از OAuth 2.0 برای تلویزیون و برنامه های دستگاه ورودی محدود استفاده می کند.

برنامه شما از طرف یک کاربر Ambient API با Ambient API تعامل دارد. کاربر این درخواست های API را با استفاده از پروتکل OAuth 2.0 مجاز می کند.

شناسه مشتری OAuth 2.0 به کاربران برنامه شما اجازه می دهد تا وارد سیستم شوند، احراز هویت کنند، و در نتیجه از Ambient API استفاده کنند. Ambient API از حساب‌های سرویس پشتیبانی نمی‌کند. برای استفاده از این APIها، کاربران باید به یک حساب Google معتبر وارد شوند.

برنامه خود را پیکربندی کنید

ابتدا API را فعال کنید، سپس یک شناسه مشتری OAuth 2.0 درخواست کنید.

API را فعال کنید

قبل از اینکه بتوانید از Ambient API استفاده کنید، باید آن را در پروژه خود فعال کنید.

1. به کنسول API Google بروید.
2. از نوار منو، یک پروژه را انتخاب کنید یا یک پروژه جدید ایجاد کنید.
3. برای باز کردن یکی از APIهای Google Photos، از منوی پیمایش، APIs & Services > Library را انتخاب کنید.
4. "Ambient API" را جستجو کنید. Ambient API را انتخاب کنید و روی Enable کلیک کنید.

شناسه مشتری OAuth 2.0 را درخواست کنید

برای درخواست شناسه مشتری OAuth و پیکربندی آن برای برنامه خود، این مراحل را دنبال کنید. Ambient API از OAuth 2.0 برای تلویزیون و برنامه های دستگاه ورودی محدود استفاده می کند.

1. به کنسول API Google بروید و پروژه خود را انتخاب کنید.
2. از منو، APIs & Services > Credentials را انتخاب کنید.

3. در صفحه اعتبارنامه ، روی ایجاد اعتبارنامه > شناسه مشتری OAuth کلیک کنید.

   توجه: اگر در حال راه اندازی یک پروژه جدید هستید، ممکن است از شما خواسته شود صفحه رضایت پروژه خود را پیکربندی کنید.

4. نوع برنامه خود را انتخاب کنید. در این مثال، نوع برنامه تلویزیون‌ها و دستگاه‌های ورودی محدود است.

5. یک نام برای مشتری OAuth 2.0 خود وارد کنید و روی ایجاد کلیک کنید.

6. از کادر گفتگوی مشتری OAuth، موارد زیر را کپی کنید:

   • شناسه مشتری
   • راز مشتری

برنامه شما می‌تواند با استفاده از این مقادیر به Google APIهای فعال دسترسی پیدا کند.

قبل از اینکه بتوانید یک برنامه عمومی را راه اندازی کنید که به Ambient API دسترسی دارد، برنامه شما باید توسط Google بررسی شود. هنگامی که برنامه خود را آزمایش می کنید، پیام "برنامه تایید نشده" روی صفحه ظاهر می شود تا زمانی که تأیید شود.

پس از پیکربندی برنامه خود، آماده شروع کار هستید. می‌توانید منابع زیر را کاوش کنید یا درباره جریان احراز هویت ساده برای Ambient API بخوانید.

• دستگاه ها را ایجاد و مدیریت کنید
• فهرست و بازیابی آیتم های رسانه ای

تغییر شناسه مشتری

منابع ایجاد شده از طریق هر یک از APIهای Google Photos فقط با استفاده از شناسه مشتری اصلی که برای ایجاد آنها استفاده شده است قابل دسترسی یا اصلاح هستند. به عنوان مثال، اگر یک session در Picker API با شناسه مشتری خاص ایجاد کنید و بعداً آن شناسه مشتری را در برنامه خود تغییر دهید، برنامه شما دسترسی به منابع API ایجاد شده با شناسه مشتری قبلی را از دست خواهد داد.

با دقت برنامه ریزی کنید و نوع شناسه مشتری مناسب را برای Photos API که استفاده می کنید انتخاب کنید. شناسه مشتری خود را فقط در صورت لزوم تغییر دهید تا از مشکلات دسترسی جلوگیری کنید.

جریان احراز هویت ساده برای Ambient API

جریان احراز هویت استاندارد Ambient API به کاربران شما نیاز دارد که 2 کد QR را اسکن کنند:

• اولین مورد برای ورود به حساب Google خود (اگر قبلاً وارد سیستم نشده باشند).
• مورد دوم که به دستگاه Ambient تازه ایجاد شده در حساب Google Photos خود پیوند می‌دهد تا بتوانند موارد رسانه را برای نمایش انتخاب کنند.

جریان ساده به شما امکان می دهد با ارسال پارامتر state اضافی با تماس احراز هویت اولیه، یک کد QR واحد را به کاربران خود ارائه دهید.

هنگام درخواست کدهای دستگاه و کاربر به‌عنوان بخشی از OAuth برای دستگاه‌های ورودی محدود ، پارامتر state اضافی را به درخواست خود اضافه کنید. موارد زیر را به پارامتر state اضافه کنید:

پارامترها
requestId	string مورد نیاز. یک شناسه منحصر به فرد ارائه شده توسط مشتری برای این درخواست. این برای کاهش تکرار منابع در صورت خرابی شبکه استفاده می شود. این شناسه باید فرمت یک رشته UUID (نسخه 4) داشته باشد و شرایط زیر را رعایت کند: نباید حاوی هیچ گونه اطلاعات شناسایی حساس در مورد کاربر باشد. باید شامل 32 نویسه هگزا دسیمال باشد که به پنج گروه جدا شده با خط تیره، با قالب "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 است که به کاربر نشان می‌دهید (به احتمال زیاد به عنوان یک کد QR) تا بتواند در دستگاه جداگانه‌ای به آنجا پیمایش کند. با گنجاندن پارامتر state ، زمانی که بعداً createDevice با Ambient API فراخوانی می‌کنید، می‌توانید از ارائه settingsUri در یک کد QR دوم صرفنظر کنید، زیرا آخرین مرحله در جریان 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. پاسخ بعدی به درخواست نظرسنجی شما حاوی نشانه‌هایی است که برنامه شما برای تأیید درخواست‌ها از طرف کاربر به آن نیاز دارد. (اگر کاربر از دسترسی به برنامه شما امتناع کرد، پاسخ حاوی توکن نیست.)

جریان API محیطی:

1. یک نشانه OAuth موجود را بررسی کنید و یا آن را تازه کنید یا یک نشانه جدید درخواست کنید.
2. پس از دریافت نشانه OAuth، یک دستگاه جدید ایجاد کنید.
3. settingsUri به کاربر نمایش دهید و شروع به نظرسنجی از دستگاه کنید تا زمانی که mediaSourcesSet true را برگرداند.
4. کاربر به settingsUri می رود و عکس هایی را که می خواهد با برنامه شما به اشتراک بگذارد انتخاب می کند.
5. هنگامی که mediaSourcesSet true را برگرداند، لیست mediaItems را بازیابی کنید.
6. اکنون می توانید نمایش اسلاید یا سایر تجربه های محیطی خود را شروع کنید.

هر دو جریان شامل مرحله‌ای هستند که در آن یک URL را به کاربر خود نشان می‌دهید، و کاربر شما در دستگاه ورودی غنی‌تر خود به آنجا پیمایش می‌کند. با گنجاندن پارامتر state در تماس اولیه OAuth خود، می توانید از نشانی اینترنتی دومی که باید نمایش دهید اجتناب کنید.

این کار به این دلیل کار می‌کند که آخرین مرحله OAuth 2.0 برای جریان برنامه‌های تلویزیون و دستگاه ورودی محدود، معمولاً کاربر شما را به صفحه‌ای هدایت می‌کند که می‌گوید «اکنون می‌توانید به دستگاه خود بازگردید». با گنجاندن پارامتر حالت، آخرین مرحله جریان اکنون سعی می کند شما را به settingsUri هدایت کند. برنامه شما همچنان یک نشانه OAuth دریافت خواهد کرد. باید از این نشانه برای فراخوانی createDevice با استفاده از همان requestId استفاده کنید. هنگامی که دستگاهی با همان شناسه ایجاد شد، جریان اولیه OAuth با موفقیت کاربر شما را به صفحه صحیح در دستگاه غنی در برنامه Photos هدایت می‌کند.

نکات زیر را به خاطر بسپارید:

• در صورت وجود هرگونه مشکلی در احراز هویت، همچنان ایده خوبی است که settingsUri نمایش دهید.
• همچنان می‌توانید settingsUri در موارد دیگر استفاده کنید، مانند زمانی که کاربر می‌خواهد انتخاب عکس خود را به‌روزرسانی کند.