با مجموعهها، منظم بمانید
ذخیره و طبقهبندی محتوا براساس اولویتهای شما.
Google Picker API راهی است که به کاربران اجازه می‌دهد فایل‌های Google Drive را انتخاب یا آپلود کنند. کاربران می‌توانند به برنامه‌های دسکتاپ شما اجازه دسترسی به داده‌های Drive خود را بدهند و روشی امن و مجاز برای تعامل با فایل‌های خود ارائه دهند.
Google Picker به عنوان یک گفتگوی "فایل باز" برای فایل های ذخیره شده در Drive عمل می کند و دارای چندین ویژگی است:
چندین نما که پیش نمایش ها و تصاویر کوچک فایل های Drive را نشان می دهد.
تغییر مسیر به Google Picker در یک برگه جدید در مرورگر پیش فرض کاربر.
توجه داشته باشید که Google Picker به کاربران اجازه سازماندهی، انتقال یا کپی فایل ها را از یک پوشه به پوشه دیگر نمی دهد. برای مدیریت فایل‌ها، باید از Google Drive API یا Drive UI استفاده کنید.
پیش نیازها
برنامه‌هایی که از Google Picker استفاده می‌کنند باید همه شرایط خدمات موجود را رعایت کنند. مهمتر از همه، شما باید به درستی خود را در درخواست های خود شناسایی کنید.
یک کلید API یک رشته طولانی است که شامل حروف بزرگ و کوچک، اعداد، زیرخط و خط فاصله است، مانند AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe . این روش احراز هویت برای دسترسی ناشناس به داده‌های در دسترس عموم استفاده می‌شود، مانند فایل‌های Google Workspace که با استفاده از تنظیمات اشتراک‌گذاری «هر کسی در اینترنت با این پیوند» به اشتراک گذاشته شده است. برای جزئیات بیشتر، به مدیریت کلیدهای API مراجعه کنید.
برای ایجاد یک کلید API:
در کنسول Google Cloud، به menu>APIs & Services>Credentials بروید.
روی Copy content_copy کلیک کنید تا کلید API خود را برای استفاده در کد برنامه خود کپی کنید. کلید API را می‌توانید در بخش «کلیدهای API» اعتبار پروژه‌تان پیدا کنید.
برای جلوگیری از استفاده غیرمجاز، توصیه می‌کنیم کلید API را در کجا و برای کدام APIها محدود کنید. برای جزئیات بیشتر، به افزودن محدودیت‌های API مراجعه کنید.
اعتبارنامه یک برنامه دسکتاپ را تأیید کنید
برای احراز هویت کاربران نهایی و دسترسی به داده های کاربر در برنامه خود، باید یک یا چند شناسه مشتری OAuth 2.0 ایجاد کنید. شناسه مشتری برای شناسایی یک برنامه واحد در سرورهای OAuth Google استفاده می شود. اگر برنامه شما روی چندین پلتفرم اجرا می شود، باید برای هر پلتفرم یک شناسه مشتری جداگانه ایجاد کنید.
در کنسول Google Cloud، به menu> برویدGoogle Auth platform>مشتریان
توکن OAuth 2.0 را به Drive API برای خواندن و اصلاح فایل‌هایی که کاربر قبلاً به آنها اجازه دسترسی داده است، منتقل کنید.
Google Picker را نمایش دهید
Google Picker API برای برنامه‌های دسکتاپ در یک برگه جدید در مرورگر پیش‌فرض کاربر به Google Picker هدایت می‌شود. هنگامی که کاربر اجازه دسترسی داد و فایل‌های مربوطه را انتخاب کرد، Google Picker از طریق URL بازگشت به تماس به برنامه تماس بازمی‌گردد. برای باز کردن Google Picker API در صفحه مشتری، به جای آن از Google Picker API برای برنامه‌های وب استفاده کنید. برای اطلاعات بیشتر، به نمای کلی برنامه های وب مراجعه کنید.
برای اجازه دادن به کاربران برای دسترسی به فایل‌های اضافی یا انتخاب فایل‌ها برای استفاده در جریان برنامه دسکتاپ، این مراحل را دنبال کنید:
شما باید پارامترهای URL prompt و trigger_onepick را به درخواست URL مجوز OAuth 2.0 خود اضافه کنید. همچنین می‌توانید Google Picker را با چندین پارامتر اختیاری سفارشی کنید:
پارامتر
توضیحات
وضعیت
prompt=consent
درخواست دسترسی به فایل
مورد نیاز
trigger_onepick=true
Google Picker را فعال کنید.
مورد نیاز
allow_multiple=true
اگر درست است، به کاربر اجازه دهید چندین فایل را انتخاب کند.
اختیاری
mimetypes= MIMETYPES
لیستی از انواع MIME جدا شده با کاما برای فیلتر کردن نتایج جستجو. اگر تنظیم نشود، فایل‌های مربوط به انواع MIME در نمای نمایش داده می‌شوند.
اختیاری
file_ids= FILE_IDS
فهرستی از شناسه‌های فایل جدا شده با کاما برای فیلتر کردن نتایج جستجو. اگر تنظیم نشود، همه فایل ها در نمای نمایش داده می شوند.
اختیاری
نمونه زیر یک درخواست URL مجوز OAuth 2.0 را نشان می دهد:
REDIRECT_URI : جایی که سرور مجوز، مرورگر کاربر را پس از احراز هویت موفقیت‌آمیز هدایت می‌کند. به عنوان مثال، https://www.cymbalgroup.com/oauth2callback .
redirect_uri مشخص شده باید یک URL عمومی HTTPS باشد. اگر می‌خواهید از پروتکل سفارشی یا URL لوکال هاست برای redirect_uri خود استفاده کنید، باید از یک URL عمومی HTTPS استفاده کنید که سپس به پروتکل سفارشی یا URL localhost هدایت می‌شود.
هنگامی که کاربر اجازه دسترسی داد و فایل های مربوطه را انتخاب کرد، OAuth به redirect_uri مشخص شده در درخواست با پارامترهای URL زیر ضمیمه شده است:
picked_file_ids : اگر کاربر اجازه دسترسی داده و فایل‌ها را انتخاب کند، فهرستی از شناسه‌های فایل انتخابی جدا شده با کاما.
code : رمز دسترسی یا کد دسترسی بر اساس پارامتر response_type تنظیم شده در درخواست. این پارامتر شامل یک کد مجوز جدید است.
scope : محدوده (های) موجود در درخواست.
error : اگر کاربر درخواست را در جریان رضایت لغو کند، یک خطا نشان داده می شود.
نمونه زیر یک پاسخ URL مجوز OAuth 2.0 را نشان می دهد:
سپس برنامه‌ها می‌توانند از شناسه‌های فایل از پارامتر URL در مرحله 3 و نشانه OAuth 2.0 به‌دست‌آمده در مرحله 4 برای فراخوانی Drive API استفاده کنند. برای اطلاعات بیشتر، نمای کلی Google Drive API را ببینید.
تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی.
[null,null,["تاریخ آخرین بهروزرسانی 2025-08-29 بهوقت ساعت هماهنگ جهانی."],[],[],null,["| **Note:** This is a **beta release** of the Google Picker API for desktop apps.\n\nThe Google Picker API is a way to let users select or upload Google Drive files.\nUsers can grant permission to your desktop apps to access their\nDrive data, providing a secure and authorized way to interact\nwith their files.\n\nThe Google Picker acts as a \"File Open\" dialog for files stored on\nDrive and has several features:\n\n- A similar look and feel to the [Google Drive\n UI](https://drive.google.com).\n- Several views showing previews and thumbnail images of Drive files.\n- A redirect to the Google Picker within a new tab in the user's default browser.\n\nNote that the Google Picker doesn't allow users to organize, move, or copy\nfiles from one folder to another. To manage files, you must use either the [Google Drive API](/workspace/drive/api/guides/about-sdk) or the Drive UI.\n\nPrerequisites\n\nApps using the Google Picker must abide by all existing [Terms of\nService](/workspace/terms). Most importantly, you must correctly identify\nyourself in your requests.\n\nYou must also have a [Google Cloud project](/workspace/guides/create-project).\n\nSet up your environment\n\nTo start using the Google Picker API, you must set up your environment.\n\nEnable the API Before using Google APIs, you need to turn them on in a Google Cloud project. You can turn on one or more APIs in a single Google Cloud project.\n\n- In the Google Cloud console, enable the Google Picker API.\n\n [Enable the API](https://console.cloud.google.com/flows/enableapi?apiid=picker.googleapis.com)\n\nCreate an API key\n\nAn API key is a long string containing upper and lower case letters, numbers,\nunderscores, and hyphens, such as `AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe`.\nThis authentication method is used to anonymously access publicly available\ndata, such as Google Workspace files shared using the \"Anyone on the Internet\nwith this link\" sharing setting. For more details, see [Manage API\nkeys](https://cloud.google.com/docs/authentication/api-keys).\n\nTo create an API key:\n\n1. In the Google Cloud console, go to Menu menu \\\u003e **APIs \\& Services** \\\u003e **Credentials** .\n\n [Go to Credentials](https://console.cloud.google.com/apis/credentials)\n2. Click **Create credentials** \\\u003e **API key**.\n3. Your new API key is displayed.\n - Click Copy content_copy to copy your API key for use in your app's code. The API key can also be found in the \"API Keys\" section of your project's credentials.\n - To prevent unauthorized use, we recommend restricting where and for which APIs the API key can be used. For more details, see [Add API restrictions](https://cloud.google.com/docs/authentication/api-keys#adding-api-restrictions).\n\nAuthorize credentials for a desktop app To authenticate end users and access user data in your app, you need to create one or more OAuth 2.0 Client IDs. A client ID is used to identify a single app to Google's OAuth servers. If your app runs on multiple platforms, you must create a separate client ID for each platform.\n\n1. In the Google Cloud console, go to Menu menu \\\u003e **Google Auth platform** \\\u003e **Clients** .\n\n [Go to Clients](https://console.cloud.google.com/auth/clients)\n2. Click **Create Client**.\n3. Click **Application type** \\\u003e **Desktop app**.\n4. In the **Name** field, type a name for the credential. This name is only shown in the Google Cloud console.\n5. Click **Create** .\n\n\n The newly created credential appears under \"OAuth 2.0 Client IDs.\"\n\nFor apps to get authorization to files previously granted to them, you must use\nthe following steps:\n\n1. You must obtain an OAuth 2.0 token with the `drive.file`, `drive`, or\n `drive.readonly` scope using these instructions: [Using OAuth 2.0 to Access\n Google APIs](/identity/protocols/oauth2). For more information on scopes,\n see [Choose Google Drive API scopes](/workspace/drive/api/guides/api-specific-auth).\n\n2. Pass the OAuth 2.0 token to the Drive API to read and modify files\n in which the user previously granted access.\n\nDisplay the Google Picker\n\nThe Google Picker API for desktop apps redirects to the Google Picker within a\nnew tab in the user's default browser. Once the user grants access and picks the\nrelevant files, the Google Picker returns to the calling app through the\ncallback URL. To have the Google Picker API open in a client page, use the\nGoogle Picker API for web apps instead. For more information, see [Overview of web\napps](/workspace/drive/picker/guides/overview).\n\nTo allow users to grant access to additional files or to pick files for use in\nyour desktop app flow, follow these steps:\n\n1. Request access to the `drive.file` scope to open the OAuth 2.0 access page\n in a new browser tab using these instructions: [Using OAuth 2.0 to Access\n Google APIs](/identity/protocols/oauth2). For more information on scopes,\n see [Choose Google Drive API scopes](/workspace/drive/api/guides/api-specific-auth).\n\n Note that only the `drive.file` scope is permitted for desktop apps and it\n can't be combined with any other scope.\n2. The URL for the new browser tab accepts all [standard OAuth query string\n parameters](/identity/protocols/oauth2/native-app#step-2:-send-a-request-to-googles-oauth-2.0-server).\n\n You must append the `prompt` and `trigger_onepick` URL parameters to your\n OAuth 2.0 authorization URL request. You can also customize the\n Google Picker with several optional parameters:\n\n | Parameter | Description | Status |\n |-------------------------------------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------|\n | `prompt=consent` | Prompt for file access. | Required |\n | `trigger_onepick=true` | Enable the Google Picker. | Required |\n | `allow_multiple=true` | If true, allow the user to select multiple files. | Optional |\n | `mimetypes=`\u003cvar translate=\"no\"\u003eMIMETYPES\u003c/var\u003e | A comma-separated list of [MIME types](/workspace/drive/api/guides/mime-types) to filter the search results. If not set, files for all MIME types are displayed in the view. | Optional |\n | `file_ids=`\u003cvar translate=\"no\"\u003eFILE_IDS\u003c/var\u003e | A comma-separated list of file IDs to filter the search results. If not set, all files are displayed in the view. | Optional |\n\n The following sample shows an OAuth 2.0 authorization URL request: \n\n https://accounts.google.com/o/oauth2/v2/auth? \\\n client_id=\u003cvar translate=\"no\"\u003eCLIENT_ID\u003c/var\u003e \\\n &scope=https://www.googleapis.com/auth/drive.file \\\n &redirect_uri=\u003cvar translate=\"no\"\u003eREDIRECT_URI\u003c/var\u003e \\\n &response_type=code \\\n &access_type=offline \\\n &prompt=consent \\\n &trigger_onepick=true\n\n Replace the following:\n - \u003cvar translate=\"no\"\u003eCLIENT_ID\u003c/var\u003e: Your desktop app's client ID.\n\n - \u003cvar translate=\"no\"\u003eREDIRECT_URI\u003c/var\u003e: Where the authorization server\n redirects the user's browser after successful authentication. For\n example, `https://www.cymbalgroup.com/oauth2callback`.\n\n The specified `redirect_uri` must be a public HTTPS URL. If you want to use\n a custom protocol or localhost URL for your `redirect_uri`, you must use a\n public HTTPS URL that then redirects to the custom protocol or localhost\n URL.\n3. Once the user grants access and picks the relevant files, OAuth redirects to\n the `redirect_uri` specified in the request with the following URL\n parameters appended:\n\n - `picked_file_ids`: If the user granted access and picked files, a\n comma-separated list of selected file IDs.\n\n - `code`: The access token or access code based on the `response_type`\n parameter set in the request. This parameter includes a new\n [authorization code](/identity/protocols/oauth2#installed).\n\n - `scope`: The scope(s) included in the request.\n\n - `error`: If the user cancelled the request within the consent flow, an\n error is shown.\n\n The following sample shows an OAuth 2.0 authorization URL response: \n\n https://\u003cvar class=\"readonly\" translate=\"no\"\u003eREDIRECT_URI\u003c/var\u003e?picked_file_ids=\u003cvar class=\"readonly\" translate=\"no\"\u003ePICKED_FILE_IDS\u003c/var\u003e&code=\u003cvar class=\"readonly\" translate=\"no\"\u003eCODE\u003c/var\u003e&scope=\u003cvar class=\"readonly\" translate=\"no\"\u003eSCOPES\u003c/var\u003e\n\n4. Apps must exchange the authorization code from step 3 for a new OAuth 2.0\n token. For more information, see [Exchange authorization code for refresh\n and access\n tokens](/identity/protocols/oauth2/web-server#exchange-authorization-code).\n\n5. Apps can then use the file IDs from the URL parameter in step 3 and OAuth\n 2.0 token obtained in step 4 to call the Drive API. For more\n information, see [Google Drive API overview](/workspace/drive/api/guides/about-sdk)."]]
