ينشئ مستكشف واجهات برمجة التطبيقات في Google نماذج رموز بشكل ديناميكي. وتم تصميم عيّنات التعليمات البرمجية هذه لنسخها وتشغيلها محليًا. لعرض النماذج، انقر على رمز ملء الشاشة
في اللوحة الجانبية لـ APIs Explorer. يوضّح الشكل التالي مستكشف واجهات برمجة التطبيقات الموسّع بملء الشاشة:يعرض مستكشف واجهات برمجة التطبيقات بشكل تلقائي كيفية استخدام cURL لتنفيذ طلبك. ويمكن أن تعرض بعض واجهات برمجة التطبيقات أيضًا نماذج للغات أخرى، مثل JavaScript وJava وPython.
تشغيل عيّنات التعليمات البرمجية محليًا
توضّح علامات التبويب التالية المتطلبات الأساسية والخطوات اللازمة لتشغيل نماذج الرموز. لتشغيل نماذج الرموز، عليك إنشاء بيانات اعتماد التفويض واستخدامها. للحصول على شرح حول كيفية إنشاء مشروع وإنشاء بيانات اعتماد، راجع مستندات واجهة برمجة تطبيقات Google الخاصة بك.
تعتمد بيانات الاعتماد على ما يلي، وذلك استنادًا إلى نوع البيانات (العامة أو الخاصة) التي تصل إليها الطريقة:
- بالنسبة إلى البيانات العلنية، تكون بيانات الاعتماد مفتاح واجهة برمجة تطبيقات.
بالنسبة إلى البيانات الخاصة، تكون بيانات الاعتماد هي ملف
client_secret.json
يحتوي على معرِّف عميل OAuth 2.0 وسر العميل أو رمز الدخول OAuth 2.0.
عنوان cURL
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- في Cloud Console، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات.
- في Cloud Console، يمكنك إنشاء بيانات اعتماد معرِّف عميل بروتوكول OAuth لتطبيق ويب واستخدام
https://developers.google.com/oauthplayground
كعنوان URL لإعادة التوجيه. - في مساحة لعب OAuth 2.0، انقر على ضبط OAuth 2.0 .
- ضع علامة في المربع استخدام بيانات الاعتماد الخاصة بك.
- أدخِل معرِّف العميل وسر العميل الذي تم إنشاؤه في الخطوة 3.
- في حقل النطاقات، اكتب النطاق المطلوب استخدامه مع طريقتك وانقر على تفويض واجهات برمجة التطبيقات.
- (اختياري) إذا ظهر لك مع شاشة تسجيل الدخول، اختَر الحساب المطلوب استخدامه.
- (اختياري) إذا تم عرض شاشة التفويض، انقر على قبول.
- انقر على رمز تفويض Exchange للرموز المميزة. يتم عرض رمز مميز.
- في نموذج رمز cURL، استبدِل
[YOUR_API_KEY]
بمفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه في الخطوة 2:'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
- في نموذج رمز cURL، استبدل
[YOUR_ACCESS_TOKEN]
برمز الدخول الذي تم إنشاؤه في الخطوة 10:--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
تنفيذ نموذج الرمز
من سطر الأوامر، نفِّذ الأمر cURL. يجب أن يكون الأمر مشابهًا لما يلي:
curl \
'https://www.googleapis.com/drive/v3/files?key=AIzaSyBiKcaoXmVApwnT24hitQG_dwjGvAj6Ddw' \
--header 'Authorization: Bearer ya29.a0ARrdaM_yQn9MWBpJgKPx880BSnRYIizRYIDz0JN9e66nSliIYpqNXmPsvv2ccfplCTG_U4b1' \
--header 'Accept: application/json' \
--compressed
JavaScript
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- في Cloud Console، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات.
- في وحدة تحكم السحابة الإلكترونية، أنشئ بيانات اعتماد معرِّف عميل OAuth لـ "Application;Web;application"، واضبط أصول JavaScript المصرَّح بها لتحديد عنوان URL الذي سترسل منه طلبات، مثل
http://localhost
. - انسخ نموذج الرمز الكامل إلى ملف محلي يمكن الوصول إليه من قِبل خادم الويب،
مثل
/var/www/html/example.html
. ابحث عن السطر في نموذج الرمز الذي يضبط مفتاح واجهة برمجة التطبيقات أو معرِّف العميل واستبدل القيمة بالقيم التي تم إنشاؤها في الخطوتين 2 و3:
- مفتاح واجهة برمجة التطبيقات:
gapi.client.setApiKey(YOUR_API_KEY);
- معرّف عميل OAuth 2.0:
gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',
- مفتاح واجهة برمجة التطبيقات:
تنفيذ نموذج الرمز
- افتح الملف في المتصفّح الذي تستخدمه، مثل
http://localhost/example.html
. نقترح عليك استخدام متصفّح مع وحدة تحكّم تصحيح أخطاء، مثل Google Chrome. - (اختياري) إذا ظهر لك مع شاشة تسجيل الدخول، اختَر الحساب المطلوب استخدامه.
- (اختياري) إذا تم عرض شاشة التفويض، انقر على قبول. يجب أن تعرض وحدة تصحيح الأخطاء استجابة الطريقة ككائن JSON.
Java
المتطلبات الأساسية
- Java 1.7 أو إصدار أحدث.
- الحصّة رقم 7 أو أكثر.
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
- اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
- إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه
client_secret_CLIENTID.json
، حيث يكونCLIENTID
هو معرِّف العميل لمشروعك. في دليل العمل، شغِّل الأوامر التالية لإنشاء بنية مشروع جديدة:
$ gradle init --type basic $ mkdir -p src/main/java src/main/resources
وإذا أنشأت معرِّف عميل OAuth 2.0 في الخطوة 2، أعِد تسمية ملف JSON الذي نزَّلته إلى
client_secret.json
.احفظ الملف الذي تمت إعادة تسميته في دليل
src/main/resources
الذي أنشأته في الخطوة 5.في دليل العمل، افتح ملف
build.gradle
واستبدِل محتواه بما يلي:apply plugin: 'java' apply plugin: 'application' mainClassName = 'ApiExample' sourceCompatibility = 1.7 targetCompatibility = 1.7 version = '1.0' repositories { mavenCentral() } dependencies { compile 'com.google.api-client:google-api-client:1.23.0' compile 'com.google.oauth-client:google-oauth-client-jetty:1.23.0' API_SPECIFIC_DEPENDENCY }
في ملف
build.gradle
، استبدل السطر الذي يشير إلىAPI_SPECIFIC_DEPENDENCY
بتعليمات لتجميع الرمز لواجهة برمجة التطبيقات التي تريد طلبها. في ما يلي نموذج لواجهة برمجة التطبيقات في "إحصاءات YouTube":compile 'com.google.apis:google-api-services-youtubeAnalytics:v2-rev16-1.23.0'
تتبع التعليمات هذا النموذج:
compile 'com.google.apis:google-api-services-API_NAME:API_VERSION- revREVISION-CL_VERSION'
المكان:
API_NAME
هو اسم واجهة برمجة التطبيقات المُدرج في GitHub لواجهة برمجة التطبيقات. للعثور على الاسم، انقر على رابط الإصدار بجانب واجهة برمجة التطبيقات في صفحة واجهات برمجة تطبيقات Google المتوافقة. ينقل رابط الإصدار إلى GitHub. يظهر اسم واجهة برمجة التطبيقات في وسط الصفحة، ويسبقه الرمزgoogleapis/google-apis-services-
. على سبيل المثال، بالنسبة إلى الإصدار 3 من Drive API، تكون قيمةAPI_NAME
هيdrive
.API_VERSION
هو إصدار واجهة برمجة التطبيقات المدرَج لواجهة برمجة التطبيقات أسفل اسم API في صفحة Google APIs المتوافقة.REVISION
هو رقم المراجعة المذكور في مرجع JavaDoc لواجهة برمجة التطبيقات. يمكن العثور على مرجع JavaScript علىhttps://googleapis.dev/java/google-api-services-API_NAME/latest/index.html
CL_VERSION
هو إصدار مكتبة العميل. تظهر هذه القيمة أيضًا في مرجع JavaDoc.- من دليل العمل، انسخ نموذج الرمز من "مستكشف واجهات برمجة التطبيقات" إلى
src/main/java/ApiExample.java
. (اسم الفئة في كل عيّنة هوApiExample
بحيث لا تحتاج إلى تعديل ملفbuild.gradle
لتشغيل نماذج مختلفة).
تنفيذ نموذج الرمز
استخدِم الأمر التالي لتشغيل المثال:
gradle -q run
يجب أن ينفذ النموذج طلب البيانات من واجهة برمجة التطبيقات ويطبع الرد على STDOUT
.
يمكنك أيضًا التحقق من الخدمة التي تتصل بها لمعرفة تأثيرات الطلبات
التي تكتب البيانات.
Node.js
المتطلبات الأساسية
- Node.js
مكتبة برامج Google APIs لـ Node.js:
- إذا لم يسبق لك تثبيت مكتبة العميل، شغِّل الأمر:
npm install googleapis --save
- إذا سبق لك تثبيت مكتبة العميل، ننصحك بتعديلها لضمان توفُّر أحدث فئات المكتبة التي تختبرها. لتعديل مكتبة العميل، شغِّل الأمر:
npm update googleapis --save
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
- اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
- إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه
client_secret_CLIENTID.json
، حيث يكونCLIENTID
هو معرِّف العميل لمشروعك. - انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي
YOUR_API_KEY
، وموقع ملف أسرار العميل هوYOUR_CLIENT_SECRET_FILE.json
.
تنفيذ نموذج الرمز
استخدِم الأمر التالي لتشغيل المثال:
node sample.js
تطبع معظم النماذج ردًا من واجهة برمجة التطبيقات (أو شيء آخر) على STDOUT
.
PHP
المتطلبات الأساسية
- الإصدار 5.4 من PHP أو الإصدارات الأحدث باستخدام واجهة سطر الأوامر (CLI) وإضافة JSON.
- تم تثبيت أداة إدارة الاعتماد على الملحِّنين في جميع أنحاء العالم.
مكتبة برامج Google APIs للغة PHP:
إذا لم يسبق لك تثبيت مكتبة العميل، شغِّل الأمر:
composer require google/apiclient:^2.0
إذا سبق لك تثبيت مكتبة العملاء، ننصحك بتعديلها لضمان توفّر أحدث فئات المكتبة التي تختبرها. لتعديل مكتبة العميل، شغِّل الأمر:
composer update google/apiclient --with-dependencies
تنفيذ نموذج الرمز
استخدِم الأمر التالي لتشغيل المثال:
php sample.php
تطبع معظم النماذج ردًا من واجهة برمجة التطبيقات (أو شيء آخر) على STDOUT
.
Python
المتطلبات الأساسية
- Python 2.7 أو Python 3.5 أو الإصدارات الأحدث
- أداة "إدارة الحزم الخاصة بنافذة ضمن النافذة"
مكتبة برامج Google APIs لبرنامج Python:
pip install --upgrade google-api-python-client
google-auth-oauthlib
وgoogle-auth-httplib2
المكتبات لتفويض المستخدم:pip install --upgrade google-auth-oauthlib google-auth-httplib2
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
- اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
- إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه
client_secret_CLIENTID.json
، حيث يكونCLIENTID
هو معرِّف العميل لمشروعك. - انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي
YOUR_API_KEY
، وموقع ملف أسرار العميل هوYOUR_CLIENT_SECRET_FILE.json
.
تنفيذ نموذج الرمز
استخدِم الأمر التالي لتشغيل المثال:
python sample.py
تطبع معظم النماذج ردًا من واجهة برمجة التطبيقات (أو شيء آخر) على STDOUT
.
Ruby
المتطلبات الأساسية
- الإصدار 2.0 أو الإصدارات الأحدث من Ruby
مكتبة عميل Google APIs لخدمة Ruby:
gem install google-api-client`
الإعداد
- اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
- استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
- اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
- إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه
client_secret_CLIENTID.json
، حيث يكونCLIENTID
هو معرِّف العميل لمشروعك. - انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي
YOUR_API_KEY
، وموقع ملف أسرار العميل هوYOUR_CLIENT_SECRET_FILE.json
.
تنفيذ نموذج الرمز
استخدِم الأمر التالي لتشغيل المثال:
ruby sample.rb
تطبع معظم النماذج ردًا من واجهة برمجة التطبيقات (أو شيء آخر) على STDOUT
.
تحديد مشاكل النماذج وحلّها
لا يظهر مربع حوار "التفويض"
يستخدم مستكشف واجهات برمجة التطبيقات نافذة منبثقة لمنح إمكانية الوصول إلى بياناتك الخاصة. إذا كان المتصفح يحظر النوافذ المنبثقة، لن تظهر هذه النافذة المنبثقة، ولن تتمكّن من منح حق الوصول.
إذا نقرت على "السماح"في شاشة التفويض ولم يحدث أي تغيير، جرِّب تغيير إعدادات النافذة المنبثقة في متصفحك لتفعيل النوافذ المنبثقة.
خطأ 401 أو 403
إذا ظهرت لك رسالة الخطأ 401 أو 403 عند اختبار نموذج، من المحتمل أن يرجع السبب في ذلك إلى حدوث مشكلة في أحد العناصر التالية:
- واجهة برمجة التطبيقات غير مفعّلة لمشروعك. راجِع التعليمات الخاصة بواجهة برمجة التطبيقات حول كيفية إنشاء مشروع وتفعيل واجهة برمجة تطبيقات.
- أنت تستخدم نوع تفويض غير صحيح (مفتاح واجهة برمجة التطبيقات بدلاً من OAuth 2.0).
- أنت تستخدم OAuth 2.0، ولكن مع نطاق ضيق جدًا.
- عند إعداد مفتاح واجهة برمجة التطبيقات، يمكنك إعداد قيود لمنع الاستخدام غير المصرح به لبيانات الاعتماد. ومع ذلك، لا يستوفي الطلب هذه القيود. للحصول على مزيد من المعلومات، يمكنك الاطّلاع على القسم استخدام قيود مفتاح واجهة برمجة التطبيقات.
تلقّيت تحذيرًا بشأن المحتوى المختلط.
إذا كنت تستخدم نقاط نهاية Google Cloud وكنت تشغِّل نقطة النهاية في خادم تطوير، قد يعرض المتصفّح تحذيرًا بشأن المحتوى المختلط. يحدث هذا التحذير بسبب تحميل "مستكشف واجهات برمجة التطبيقات" عبر بروتوكول HTTPS، ولكن عند تشغيل واجهة برمجة التطبيقات محليًا، تتم استضافتها على HTTP.
لإخفاء هذا التحذير باستخدام Chrome، يمكنك بدء جلسة Chrome باستخدام علامات خاصة على النحو التالي:
path/to/chrome --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:port
مثلاً:
/usr/bin/google-chrome-stable --user-data-dir=test --unsafely-treat-insecure-origin-as-secure=http://localhost:8080
ولا يجب إخفاء هذا التحذير إلا لأغراض الاختبار المحلي.
JavaScript فقط: لم يتم تحديد gapi
يحدث خطأ ولا يمكن تعريفه&، على سبيل المثال، عندما يحاول رمز JavaScript استدعاء "مكتبة عميل Google API" للغة JavaScript قبل تحميل المكتبة. تأكّد من أن الرمز الذي يشير إلى المتغيّر gapi
لا يتم طلبه إلا بعد تحميل مكتبة العميل.