تنظيم صفحاتك في مجموعات
يمكنك حفظ المحتوى وتصنيفه حسب إعداداتك المفضّلة.
تتيح واجهة برمجة تطبيقات Google Picker للمستخدمين اختيار ملفات Google Drive أو تحميلها.
يمكن للمستخدمين منح تطبيقات الكمبيوتر المكتبي الإذن بالوصول إلى بياناتهم على Drive، ما يوفّر طريقة آمنة ومصرَّح بها للتفاعل مع ملفاتهم.
يعمل "أداة اختيار الملفات من Google" كحوار "فتح ملف" للملفات المخزّنة على Drive، ويتضمّن عدة ميزات:
عدّة طرق عرض تعرض معاينات وصور مصغّرة لملفات Drive
إعادة توجيه إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم
يُرجى العِلم أنّ Google Picker لا يسمح للمستخدمين بتنظيم الملفات أو نقلها أو نسخها من مجلد إلى آخر. لإدارة الملفات، عليك استخدام
Google Drive API أو واجهة مستخدم Drive.
المتطلبات الأساسية
يجب أن تلتزم التطبيقات التي تستخدم "أداة اختيار الملفات من Google" بجميع بنود الخدمة الحالية. الأهم من ذلك، يجب أن تحدّد هويتك بشكل صحيح في طلباتك.
مفتاح واجهة برمجة التطبيقات هو سلسلة طويلة تحتوي على أحرف كبيرة وصغيرة وأرقام وشرطات سفلية وواصلات، مثل AIzaSyDaGmWKa4JsXZ-HjGw7ISLn_3namBGewQe.
يُستخدم أسلوب المصادقة هذا للوصول بشكل مجهول إلى البيانات المتاحة للجميع، مثل ملفات Google Workspace التي تتم مشاركتها باستخدام إعداد المشاركة "يمكن لأي مستخدم على الإنترنت لديه هذا الرابط الوصول إلى الملف". لمزيد من التفاصيل، يُرجى الاطّلاع على إدارة مفاتيح واجهة برمجة التطبيقات.
انقر على إنشاء بيانات اعتماد>مفتاح واجهة برمجة التطبيقات.
يظهر مفتاح واجهة برمجة التطبيقات الجديد.
انقر على "نسخ" content_copy لنسخ مفتاح واجهة برمجة التطبيقات واستخدامه في رمز تطبيقك. يمكنك أيضًا العثور على مفتاح واجهة برمجة التطبيقات في قسم "مفاتيح واجهة برمجة التطبيقات" ضمن بيانات اعتماد مشروعك.
لمنع الاستخدام غير المصرّح به، ننصحك بفرض قيود على الأماكن التي يمكن فيها استخدام مفتاح واجهة برمجة التطبيقات وعلى واجهات برمجة التطبيقات التي يمكن استخدام المفتاح معها. لمزيد من التفاصيل، يُرجى الاطّلاع على
إضافة قيود على واجهة برمجة التطبيقات.
تفويض بيانات اعتماد لتطبيق على الكمبيوتر
لمصادقة المستخدمين النهائيين والوصول إلى بيانات المستخدمين في تطبيقك، عليك إنشاء معرّف عميل واحد أو أكثر من معرّفات عملاء OAuth 2.0. يُستخدَم معرّف العميل لتحديد تطبيق واحد لخوادم OAuth من Google. إذا كان تطبيقك يعمل على منصات متعددة، عليك إنشاء معرّف عميل منفصل لكل منصة.
في "وحدة تحكّم Google Cloud"، انتقِل إلى "القائمة" menu>Google Auth platform>العملاء.
يجب تمرير رمز OAuth 2.0 المميز إلى Drive API لقراءة الملفات وتعديلها
التي سبق أن منح المستخدم إذن الوصول إليها.
عرض Google Picker
تعيد واجهة برمجة التطبيقات Google Picker لتطبيقات الكمبيوتر المكتبي التوجيه إلى Google Picker ضمن علامة تبويب جديدة في المتصفّح التلقائي للمستخدم. بعد أن يمنح المستخدم الإذن بالوصول إلى الملفات ويختار الملفات ذات الصلة، تعود أداة اختيار الملفات من Google إلى التطبيق الذي تم استدعاؤها منه من خلال عنوان 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 المحلي لجهازك.
بعد أن يمنح المستخدم الإذن بالوصول ويختار الملفات ذات الصلة، تتم إعادة توجيه 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)."]]
