پیکربندی یکپارچه‌سازی واسط کاربر Drive

برای نمایش برنامه‌تان در Google Drive وقتی کاربر فایلی را ایجاد یا باز می‌کند، باید ابتدا ادغام میانای کاربر (UI) Drive را راه‌اندازی کنید. پیکربندی برای فهرست کردن برنامه‌تان در Google Workspace Marketplace نیز لازم است.

فعال کردن Drive API

قبل‌از استفاده از Google APIs، باید آن‌ها را در پروژه Google Cloud روشن کنید. می‌توانید یک یا چند میانای برنامه‌سازی کاربردی را در یک پروژه Google Cloud روشن کنید.

برای شروع ادغام با واسط کاربر Google Drive، باید Drive API را فعال کنید. این کار به شما امکان می‌دهد به میانای برنامه‌سازی کاربردی و ویژگی‌های ادغام میانای کاربر دسترسی داشته باشید.

• در کنسول Google Cloud، میانای برنامه‌سازی کاربردی Google Drive را فعال کنید.

  فعال کردن میانای برنامه‌سازی کاربردی

راه‌اندازی یکپارچه‌سازی Drive UI

1. در «کنسول Google API»، به «منو» > میاناهای برنامه‌سازی کاربردی و سرویس‌ها > میاناهای برنامه‌سازی کاربردی و سرویس‌های فعال‌شده بروید.

   رفتن به «سرویس‌ها و میاناهای برنامه‌سازی کاربردی فعال‌شده»

2. در پایین داشبورد «میاناهای برنامه‌سازی کاربردی و سرویس‌ها»، روی Google Drive API کلیک کنید. صفحه پیکربندی Google Drive API ظاهر می‌شود.
3. برگه ادغام Drive UI را انتخاب کنید.
4. (اختیاری) نامی را در فیلد نام برنامه وارد کنید. نام برنامه در برگه «مدیریت برنامه‌ها» در تنظیمات Drive به کاربران نمایش داده می‌شود.
5. (اختیاری) شرحی کوتاه و یک‌خطی در فیلد شرح کوتاه وارد کنید. شرح کوتاه در برگه «مدیریت برنامه‌ها» در تنظیمات Drive به کاربران نمایش داده می‌شود.
6. (اختیاری) شرح کاملی در فیلد شرح کامل وارد کنید.

7. یک یا چند نماد برنامه را برای نمایش در فهرست برنامه‌های Drive متصل‌شده کاربر و در منوِ بافت «باز کردن با» بارگذاری کنید. نمادها باید در قالب PNG با پس‌زمینه شفاف باشند. ممکن است تا ۲۴ ساعت طول بکشد تا نمادها در Drive نشان داده شوند.

   توجه: نمادهای سند منسوخ شده‌اند. نماد برنامه شما در کنار فایل‌های میان‌بر و میان‌بر طرف سوم نشان داده می‌شود. برای انواع دیگر فایل‌ها، از مجموعه‌ای از نمادهای استاندارد استفاده می‌شود.

8. برای استفاده از گزینه «باز کردن با» در منوِ رابط کاربری Drive، نشانی وب برنامه‌تان را در فیلد باز کردن نشانی وب وارد کنید. این نشانی وب توسط منوِ زمینه‌ای «باز کردن با» استفاده می‌شود.

   • این نشانی وب باید حاوی نام دامنه کاملاً واجدشرایط باشد؛ localhost کار نمی‌کند.
   • این نشانی وب باید برای کاربران موردنظر برنامه‌تان دردسترس باشد. اگر چند نسخه از برنامه دارید، مثلاً یکی برای انتشار عمومی و دیگری برای انتشار محدود برای کاربران منتخب، هر نسخه باید از نشانی وب منحصربه‌فردی استفاده کند. سپس می‌توانید پیکربندی‌های مختلف برنامه را برای هر نسخه ایجاد کنید.
   • پیش‌از اینکه بتوانید برنامه‌تان را در Google Workspace Marketplace فهرست کنید، باید مالکیت این نشانی وب را به‌تأیید برسانید.
   • به‌طور پیش‌فرض، یک پارامتر پُرسمان state به این نشانی وب اضافه می‌شود تا داده‌ها را از واسط کاربر Drive به برنامه شما منتقل کند. برای اطلاعات درباره محتوای پارامتر state، به پارامتر state مراجعه کنید.
   هشدار: گزینه نمایش خودکار صفحه کسب رضایت OAuth 2.0 منسوخ شده است. این چارگوش را علامت نزنید. برنامه باید همه درخواست‌های مجوز را شروع کند.

9. (اختیاری) انواع MIME و پسوندهای فایل پیش‌فرض را در فیلدهای انواع MIME پیش‌فرض و پسوندهای فایل پیش‌فرض وارد کنید. انواع MIME پیش‌فرض و پسوندهای فایل نشان‌دهنده فایل‌هایی هستند که برنامه شما به‌طور منحصربه‌فرد برای باز کردن آن‌ها ساخته شده است. برای مثال، ممکن است برنامه‌تان قالب داخلی‌ای را برای لایه‌بندی و ویرایش تصاویر باز کند. فقط انواع رسانه استاندارد را اضافه کنید و مطمئن شوید که غلط املایی یا تایپی نداشته باشند. اگر برنامه‌تان فقط فایل‌های میان‌بر یا میان‌بر طرف سوم را باز می‌کند، می‌توانید نوع MIME را خالی بگذارید.

10. (اختیاری) انواع MIME و پسوندهای فایل ثانویه را در فیلدهای انواع MIME ثانویه و پسوندهای فایل ثانویه وارد کنید. نوع رسانه : نوع MIME ثانویه و پسوندهای فایل نشان‌دهنده فایل‌هایی هستند که برنامه‌تان می‌تواند باز کند، اما مختص برنامه‌تان نیستند. برای مثال، برنامه‌تان ممکن است برنامه ویرایش تصویری باشد که تصاویر PNG و JPG را باز می‌کند. فقط انواع رسانه استاندارد را اضافه کنید و مطمئن شوید که غلط املایی یا تایپی نداشته باشند. اگر برنامه‌تان فقط فایل‌های میان‌بر یا میان‌بر طرف سوم را باز می‌کند، می‌توانید نوع MIME را خالی بگذارید.

    توجه: اگر کاربری چند برنامه Drive نصب کند که بتوانند فایلی را باز کنند، تا زمانی که کاربر برنامه دیگری را انتخاب نکند، از برنامه‌ای که اخیراً نصب شده است استفاده می‌شود.

11. برای استفاده از دکمه «جدید» در میانای کاربری Drive و اینکه کاربران بتوانند با برنامه‌تان فایل ایجاد کنند، چارگوش ایجاد فایل را علامت بزنید. فیلدهای نشانی وب جدید و نام سند (اختیاری) ظاهر می‌شود.

    • این نشانی وب باید حاوی نام دامنه کاملاً واجدشرایط باشد؛ localhost کار نمی‌کند.
    • پیش‌از اینکه بتوانید برنامه‌تان را در Google Workspace Marketplace فهرست کنید، باید مالکیت این نشانی وب را به‌تأیید برسانید.
    • به‌طور پیش‌فرض، یک پارامتر پُرسمان state به این نشانی وب اضافه می‌شود تا داده‌ها را از واسط کاربر Drive به برنامه شما منتقل کند. برای اطلاعات درباره محتوای پارامتر state، به پارامتر state مراجعه کنید.

12. نشانی وبی را در فیلد نشانی وب جدید وارد کنید. این نشانی وب توسط دکمه «جدید» استفاده می‌شود تا کاربر را به برنامه شما هدایت کند.

    توجه: فیلد «نام سند» را خالی بگذارید. دیگر از این فیلد استفاده نمی‌شود.

13. (اختیاری) اگر می‌خواهید برنامه‌تان فایل‌های پشتیبانی‌شده Google Workspace را باز کند، چارگوش وارد کردن را علامت بزنید.

14. (اختیاری) اگر برنامه‌تان باید فایل‌ها را در درایوهای مشترک مدیریت کند، چارگوش پشتیبانی درایوهای مشترک را علامت بزنید. برای اطلاعات بیشتر درباره نحوه پشتیبانی از درایوهای مشترک در برنامه‌تان، به پیاده‌سازی پشتیبانی از درایو مشترک مراجعه کنید.

15. روی ارسال کلیک کنید.

درخواست گستره drive.install

برای اینکه برنامه‌ها به‌عنوان گزینه‌ای در منو «باز کردن با» یا «جدید» نشان داده شوند، درخواست کنید که دامنه https://www.googleapis.com/auth/drive.install با رابط کاربری Drive ادغام شود. هنگام درخواست این دامنه، کاربران کادر گفتگویی مشابه این دریافت می‌کنند:

شکل ۱. کادر گفتگوی نصب هنگام استفاده از دامنه‌ها برای Drive UI.

برای اطلاعات بیشتر درباره دامنه‌هایی که می‌توانید برای برنامه‌های Drive درخواست کنید، و نحوه درخواست آن‌ها، به اطلاعات اصالت‌سنجی و صدور مجوز مختص API مراجعه کنید.

توجه: اگر برنامه Drive خود را در Google Workspace Marketplace منتشر کنید، کاربران و سرپرستان دامنه می‌توانند برنامه را مستقیماً از Google Workspace Marketplace جستجو و نصب کنند.

پارامتر state

به‌طور پیش‌فرض، پارامتر state به هر دو «نشانی وب باز» و «نشانی وب جدید» اضافه می‌شود تا داده‌ها را از Drive UI به برنامه شما منتقل کند. این پارامتر حاوی رشته کدگذاری‌شده JSON با متغیرهای الگو و داده‌های مربوط به درخواست به برنامه شما است. متغیرهای گنجانده‌شده به نوع نشانی وب استفاده‌شده («نشانی وب باز» یا «نشانی وب جدید») بستگی دارد:

متغیر الگو	شرح	برنامه نشانی وب
{ids}	فهرست جداشده با کاما از شناسه‌های فایل درحال باز شدن.	بازکردن URL
{exportIds}	فهرست جداشده با کاما از شناسه‌های فایل درحال صادر شدن. فقط هنگام باز کردن فایل‌های Google Workspace استفاده می‌شود.	بازکردن URL
{resourceKeys}	واژه‌نامه JSON از شناسه‌های فایل که به کلیدهای منبع مربوطه نگاشت شده‌اند.	بازکردن URL
{folderId}	شناسه پوشه والد.	نشانی وب جدید
{folderResourceKey}	کلید منبع پوشه والد.	نشانی وب جدید
{userId}	شناسه نمایه‌ای که کاربر را شناسایی می‌کند.	نشانی وب باز و نشانی وب جدید
{action}	کنشی که درحال انجام است. مقدار open هنگام استفاده از «نشانی وب باز» یا create هنگام استفاده از «نشانی وب جدید» است.	نشانی وب باز و نشانی وب جدید

پارامتر state به‌صورت URL-encoded است، بنابراین برنامه‌تان باید نویسه‌های گریز را مدیریت کند و آن را به‌عنوان JSON تجزیه کند. برنامه‌ها می‌توانند مقدار create را در پارامتر state شناسایی کنند تا درخواست ایجاد فایل را درستی‌سنجی کنند.

نمونه اطلاعات وضعیت در JSON برای نشانی وب جدید

اطلاعات state برای نشانی وب جدید:

{
  "action":"create",
  "folderId":"FOLDER_ID",
  "folderResourceKey":"FOLDER_RESOURCE_KEY",
  "userId":"USER_ID"
}

نمونه اطلاعات وضعیت در JSON برای «نشانی وب باز»

اطلاعات state برای «باز کردن نشانی وب» عبارت است از:

{
  "ids": ["ID"],
  "resourceKeys":{"RESOURCE_KEYS":"RESOURCE_KEYS"},
  "action":"open",
  "userId":"USER_ID"
}

از شناسه‌ها و کلیدهای منبع برای واکشی فراداده فایل و بارگیری محتوای فایل استفاده می‌شود. وقتی برنامه‌تان شناسه فایل و کد دسترسی را دریافت کرد، می‌تواند اجازه‌ها را بررسی کند، فراداده فایل را واکشی کند، و محتوای فایل را همان‌طور که در روش files.get شرح داده شده است بارگیری کند.

توجه: همه برنامه‌ها، ازجمله برنامه‌هایی که فایل‌ها را از میان‌برها و میان‌برهای طرف سوم باز می‌کنند، باید روش files.get را فراخوانی کنند تا اجازه‌های کاربر را برای سند بررسی کنند. برنامه‌ها باید به کاربران با دسترسی فقط خواندن هشدار دهند که درحال باز کردن فایلی هستند که نمی‌توانند آن را ویرایش یا ذخیره کنند (به‌جای اینکه به آن‌ها اجازه دهند وقت خود را صرف ویرایش کنند و سپس هنگام ذخیره کردن خطا نمایش دهند).

موضوعات مرتبط

برنامه نصب‌شده باید بتواند کنش‌های راه‌اندازی‌شده از رابط کاربری Drive را ایجاد، مدیریت، و باز کند. برای کسب اطلاعات بیشتر، ادغام با دکمه «جدید» در میانای کاربری Drive یا ادغام با منوِ بافت «باز کردن با» در میانای کاربری Drive را ببینید.