مروری بر برنامه های دسکتاپ

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

ابزار انتخابگر گوگل (Google Picker) به عنوان یک پنجره‌ی «باز کردن فایل» برای فایل‌های ذخیره شده در درایو عمل می‌کند و چندین ویژگی دارد:

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

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

پیش‌نیازها

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

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

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

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

فعال کردن API

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

ایجاد کلید API

کلید API یک رشته طولانی است که شامل حروف بزرگ و کوچک، اعداد، زیرخط و خط فاصله است، مانند AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe . این روش احراز هویت برای دسترسی ناشناس به داده‌های عمومی، مانند فایل‌های Google Workspace که با استفاده از تنظیم اشتراک‌گذاری «هر کسی در اینترنت با این لینک» به اشتراک گذاشته شده است، استفاده می‌شود. برای جزئیات بیشتر، به مدیریت کلیدهای API مراجعه کنید.

برای ایجاد کلید API:

  1. در کنسول گوگل کلود، به Menu > APIs & Services > Credentials بروید.

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

  2. روی ایجاد اعتبارنامه > کلید API کلیک کنید.
  3. کلید API جدید شما نمایش داده می‌شود.
    • برای کپی کردن کلید API خود جهت استفاده در کد برنامه، روی گزینه کپی کردن کلیک کنید. کلید API را می‌توانید در بخش «کلیدهای API» در اعتبارنامه‌های پروژه خود نیز پیدا کنید.
    • برای جلوگیری از استفاده غیرمجاز، توصیه می‌کنیم مکان و نوع APIهایی که کلید API می‌تواند استفاده شود را محدود کنید. برای جزئیات بیشتر، به افزودن محدودیت‌های API مراجعه کنید.

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

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

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

  2. روی ایجاد کلاینت کلیک کنید.
  3. روی نوع برنامه > برنامه دسکتاپ کلیک کنید.
  4. در فیلد نام ، نامی برای اعتبارنامه تایپ کنید. این نام فقط در کنسول Google Cloud نمایش داده می‌شود.
  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 ارسال کنید تا فایل‌هایی را که کاربر قبلاً به آنها دسترسی داده است، بخواند و تغییر دهد.

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

رابط برنامه‌نویسی کاربردی گوگل پیکِر برای برنامه‌های دسکتاپ، کاربر را در یک تب جدید در مرورگر پیش‌فرض خود به گوگل پیکِر هدایت می‌کند. پس از اعطای دسترسی و انتخاب فایل‌های مربوطه، گوگل پیکِر از طریق URL فراخوانی به برنامه فراخوانی‌کننده بازمی‌گردد. برای باز کردن رابط برنامه‌نویسی کاربردی گوگل پیکِر در صفحه کلاینت، از رابط برنامه‌نویسی کاربردی گوگل پیکِر برای برنامه‌های وب استفاده کنید. برای اطلاعات بیشتر، به «مروری بر برنامه‌های وب» مراجعه کنید.

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

  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 فهرستی از شناسه‌های فایل که با کاما از هم جدا شده‌اند تا نتایج جستجو را فیلتر کنند. اگر تنظیم نشود، همه فایل‌ها در نما نمایش داده می‌شوند. اختیاری

    نمونه زیر یک درخواست 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 مراجعه کنید.