ادغام Google Picker در برنامه‌های دسکتاپ و موبایل

این سند نحوه ادغام Google Picker را در برنامه‌های دسکتاپ و موبایل شما با استفاده از API Google Picker توضیح می‌دهد.

API انتخابگر گوگل (Google Picker API) راهی است که به کاربران اجازه می‌دهد فایل‌های گوگل درایو را انتخاب یا آپلود کنند. کاربران می‌توانند به برنامه دسکتاپ، موبایل یا وب شما اجازه دسترسی به داده‌های درایو خود را بدهند و روشی امن و مجاز برای تعامل با فایل‌های خود فراهم کنند.

ویژگی‌ها

ابزار انتخابگر گوگل چندین ویژگی دارد:

• ظاهری مشابه رابط کاربری گوگل درایو .
• چندین نما که پیش‌نمایش‌ها و تصاویر کوچک فایل‌های Drive را نشان می‌دهند.
• نماهای از پیش فیلتر شده که فقط انواع فایل‌های خاص (مانند PDF یا تصاویر) یا پوشه‌های خاصی را نشان می‌دهند.
• تغییر مسیر به Google Picker در یک برگه جدید در مرورگر پیش‌فرض کاربر.

توجه داشته باشید که اگرچه می‌توانید با استفاده از Google Picker فایل‌ها را انتخاب و آپلود کنید، اما به کاربران اجازه سازماندهی، انتقال یا کپی فایل‌ها از یک پوشه به پوشه دیگر را نمی‌دهد. برای مدیریت فایل‌ها، باید از API گوگل درایو یا رابط کاربری درایو استفاده کنید.

پیش‌نیازها

برنامه‌هایی که از Google Picker استفاده می‌کنند باید از تمام شرایط خدمات موجود پیروی کنند. از همه مهم‌تر، شما باید در درخواست‌های خود، هویت خود را به درستی ذکر کنید.

شما همچنین باید یک پروژه Google Cloud داشته باشید.

محیط خود را تنظیم کنید

برای شروع استفاده از API انتخابگر گوگل، باید محیط خود را تنظیم کنید.

فعال کردن API

قبل از استفاده از APIهای گوگل، باید آنها را در یک پروژه گوگل کلود فعال کنید. می‌توانید یک یا چند API را در یک پروژه گوگل کلود فعال کنید.

• در کنسول گوگل کلود، Google Picker API را فعال کنید.

  فعال کردن API

تنظیم احراز هویت و مجوز

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

اعتبارنامه‌ها را برای یک برنامه دسکتاپ تأیید کنید

برای ایجاد شناسه کلاینت OAuth 2.0، مراحل زیر را دنبال کنید:

1. در کنسول API گوگل، به Menu > Google Auth platform > Clients بروید.

   به بخش مشتریان بروید

2. روی ایجاد کلاینت کلیک کنید.
3. روی نوع برنامه > برنامه دسکتاپ کلیک کنید.
4. در فیلد نام ، یک نام برای اعتبارنامه تایپ کنید. این نام فقط در کنسول API گوگل نمایش داده می‌شود.
5. روی ایجاد کلیک کنید.

   اعتبارنامه‌ی تازه ایجاد شده در زیر «OAuth 2.0 Client IDs» ظاهر می‌شود.

برای اینکه برنامه‌ها بتوانند به فایل‌هایی که قبلاً به آنها مجوز داده شده است، دسترسی پیدا کنند، باید مراحل زیر را دنبال کنید:

1. شما باید با استفاده از این دستورالعمل‌ها، یک توکن OAuth 2.0 با دامنه drive.file ، drive یا drive.readonly دریافت کنید: استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل . برای اطلاعات بیشتر در مورد دامنه‌ها، به «انتخاب دامنه‌های API گوگل درایو» مراجعه کنید.

2. توکن OAuth 2.0 را به Drive API ارسال کنید تا فایل‌هایی را که کاربر قبلاً به آنها دسترسی داده است، بخواند و تغییر دهد.

اعتبارنامه‌ها را برای برنامه تلفن همراه خود تأیید کنید

برای ایجاد شناسه کلاینت OAuth 2.0، مراحل زیر «مجاز کردن اعتبارنامه‌ها برای یک برنامه تلفن همراه» را دنبال کنید.

اعتبارنامه‌ها را برای برنامه وب خود تأیید کنید

برای ایجاد شناسه کلاینت OAuth 2.0، مراحل زیر «مجاز کردن اعتبارنامه‌ها برای یک برنامه وب» را دنبال کنید.

نمایش انتخابگر گوگل

رابط برنامه‌نویسی کاربردی (API) انتخابگر گوگل (Google Picker) برای برنامه‌های دسکتاپ و موبایل، کاربر را در یک تب جدید در مرورگر پیش‌فرض خود به انتخابگر گوگل هدایت می‌کند. پس از اعطای دسترسی و انتخاب فایل‌های مربوطه توسط کاربر، انتخابگر گوگل از طریق URL فراخوانی‌شده به برنامه فراخوانی‌کننده بازمی‌گردد.

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

برای اینکه به کاربران اجازه دهید به فایل‌های اضافی دسترسی داشته باشند یا فایل‌هایی را برای استفاده در جریان برنامه شما انتخاب کنند، این مراحل را دنبال کنید:

1. برای باز کردن صفحه دسترسی OAuth 2.0 در یک برگه مرورگر جدید، با استفاده از این دستورالعمل‌ها، درخواست دسترسی به دامنه drive.file را بدهید: استفاده از OAuth 2.0 برای دسترسی به APIهای گوگل . برای اطلاعات بیشتر در مورد دامنه‌ها، به «انتخاب دامنه‌های API گوگل درایو» مراجعه کنید.

   توجه داشته باشید که فقط دامنه drive.file برای این برنامه‌ها مجاز است و نمی‌توان آن را با هیچ دامنه دیگری ترکیب کرد.

2. آدرس اینترنتی (URL) مربوط به تب جدید مرورگر، تمام پارامترهای استاندارد رشته پرس‌وجوی OAuth را می‌پذیرد.

   شما باید پارامترهای prompt و trigger_onepick URL را به درخواست URL احراز هویت OAuth 2.0 خود اضافه کنید. به صورت اختیاری، می‌توانید Google Picker را با چندین پارامتر دیگر نیز سفارشی کنید:

   پارامتر	توضیحات	وضعیت
   prompt=consent	درخواست دسترسی به فایل.	مورد نیاز
   trigger_onepick=true	انتخابگر گوگل را فعال کنید.	مورد نیاز
   allow_multiple=true	اگر درست باشد، به کاربر اجازه می‌دهد چندین فایل را انتخاب کند.	اختیاری
   mimetypes= MIMETYPES	فهرستی از انواع MIME که با کاما از هم جدا شده‌اند تا نتایج جستجو را فیلتر کنند. اگر تنظیم نشده باشد، فایل‌های مربوط به همه انواع MIME در نما نمایش داده می‌شوند.	اختیاری
   file_ids= FILE_IDS	فهرستی از شناسه‌های فایل که با کاما از هم جدا شده‌اند تا نتایج جستجو را فیلتر کنند. اگر تنظیم نشود، همه فایل‌ها در نما نمایش داده می‌شوند.	اختیاری
   allow_folder_selection=true	اگر درست باشد، به کاربر اجازه می‌دهد پوشه‌ها را نیز انتخاب کند.	اختیاری

   نمونه زیر یک درخواست URL مجوز OAuth 2.0 را نشان می‌دهد:

   https://accounts.google.com/o/oauth2/v2/auth? \
   client_id=CLIENT_ID \
   &scope=https://www.googleapis.com/auth/drive.file \
   &redirect_uri=REDIRECT_URI \
   &response_type=code \
   &access_type=offline \
   &prompt=consent \
   &trigger_onepick=true
   

   موارد زیر را جایگزین کنید:

   • CLIENT_ID : شناسه کلاینت برنامه شما.

   • REDIRECT_URI : جایی که سرور احراز هویت پس از احراز هویت موفقیت‌آمیز، مرورگر کاربر را به آدرس دیگری هدایت می‌کند. برای مثال، https://www.cymbalgroup.com/oauth2callback .

     redirect_uri مشخص شده باید یک URL عمومی HTTPS باشد. اگر می‌خواهید از یک پروتکل سفارشی یا URL محلی برای redirect_uri خود استفاده کنید، باید از یک URL عمومی HTTPS استفاده کنید که سپس به پروتکل سفارشی یا URL محلی هدایت می‌شود.

3. زمانی که کاربر اجازه دسترسی داد و فایل‌های مربوطه را انتخاب کرد، OAuth صفحه را به redirect_uri مشخص شده در درخواست با پارامترهای URL زیر هدایت می‌کند:

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

   • code : توکن دسترسی یا کد دسترسی بر اساس پارامتر response_type که در درخواست تنظیم شده است. این پارامتر شامل یک کد مجوز جدید است.

   • scope : دامنه(های) موجود در درخواست.

   • error : اگر کاربر درخواست را در جریان رضایت لغو کرده باشد، خطایی نشان داده می‌شود.

   نمونه زیر یک پاسخ URL احراز هویت OAuth 2.0 را نشان می‌دهد:

   https://REDIRECT_URI?picked_file_ids=PICKED_FILE_IDS&code=CODE&scope=SCOPES
   

4. برنامه‌ها باید کد مجوز مرحله ۳ را با یک توکن جدید OAuth 2.0 تعویض کنند. برای اطلاعات بیشتر، به بخش کد مجوز تعویض برای توکن‌های به‌روزرسانی و دسترسی مراجعه کنید.

5. سپس برنامه‌ها می‌توانند از شناسه‌های فایل از پارامتر URL در مرحله ۳ و توکن OAuth 2.0 که در مرحله ۴ به دست آمده است، برای فراخوانی Drive API استفاده کنند. برای اطلاعات بیشتر، به نمای کلی Google Drive API مراجعه کنید.

استفاده از Google Picker با برنامه‌های اندروید

شما همچنین می‌توانید از Google Picker در برنامه‌های تلفن همراه اندروید خود استفاده کنید.

اعتبارنامه‌ها را برای یک برنامه تلفن همراه تأیید کنید

برای استفاده از Google Picker در برنامه اندروید خود، باید کاربران را با استفاده از OAuth 2.0، مشابه برنامه‌های دسکتاپ ، مجاز کنید. برای جزئیات بیشتر در مورد احراز هویت اندروید، به بخش «مجاز کردن دسترسی به داده‌های کاربر گوگل» مراجعه کنید.

برای نمایش Google Picker در طول احراز هویت، یک AuthorizationRequest ایجاد کنید و از پارامتر منبع PICKER_OAUTH_TRIGGER در شیء AuthorizationRequest.ResourceParameter استفاده کنید.

هنگام ساخت AuthorizationRequest :

• از دامنه‌ی drive.file استفاده کنید.

• تابع setOptOutIncludingGrantedScopes با true فراخوانی کنید تا مطمئن شوید توکن برگردانده شده فقط برای دامنه drive.file است و برای هیچ دامنه اعطا شده قبلی نیست.

• فیلد AuthorizationRequest.Prompt را روی CONSENT تنظیم کنید تا از کاربر درخواست رضایت کند، حتی اگر قبلاً رضایت داده شده باشد.

• شما می‌توانید به صورت اختیاری از عملگر bitmap "OR" ( | ) برای تنظیم فیلد AuthorizationRequest.Prompt به SELECT_ACCOUNT استفاده کنید تا کاربر بتواند قبل از نمایش اعلان رضایت، یک حساب کاربری را انتخاب کند.

با انتخابگر گوگل تماس بگیرید

مشابه برنامه‌های دسکتاپ، می‌توانید Google Picker را با چندین پارامتر اختیاری سفارشی کنید:

• PICKER_ALLOW_MULTIPLE : به کاربران اجازه می‌دهد چندین فایل را انتخاب کنند.
• PICKER_MIMETYPES : لیستی از انواع MIME که با کاما از هم جدا شده‌اند را برای فیلتر کردن نتایج جستجو می‌پذیرد. اگر تنظیم نشده باشد، فایل‌های مربوط به همه انواع MIME در نما نمایش داده می‌شوند.
• PICKER_FILE_IDS : فهرستی از شناسه‌های فایل که با کاما از هم جدا شده‌اند را برای فیلتر کردن نتایج جستجو می‌پذیرد. اگر تنظیم نشده باشد، همه فایل‌ها در نما نمایش داده می‌شوند.
• PICKER_ALLOW_FOLDER_SELECTION : به کاربران اجازه می‌دهد پوشه‌ها را نیز انتخاب کنند.

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

زمانی که کاربر دسترسی را اعطا کرده و فایل‌های مربوطه را انتخاب می‌کند، شیء getTokenResponseParams از منبع AuthorizationResult بازگردانده می‌شود. اگر کاربر دسترسی را اعطا کرده باشد، این شیء حاوی مقدار picked_file_ids است که لیستی از شناسه‌های فایل‌های انتخاب شده است که با کاما از هم جدا شده‌اند.

مباحث مرتبط

• انتخاب محدوده‌های API گوگل درایو