تنفيذ عينات من الرموز

ينشئ مستكشف واجهات برمجة التطبيقات في Google نماذج رموز بشكل ديناميكي. وتم تصميم عيّنات التعليمات البرمجية هذه لنسخها وتشغيلها محليًا. لعرض النماذج، انقر على رمز ملء الشاشة في اللوحة الجانبية لـ APIs Explorer. يوضّح الشكل التالي مستكشف واجهات برمجة التطبيقات الموسّع بملء الشاشة:

الشكل 2: لوحة ملء واجهة برمجة التطبيقات في "مستكشف واجهات برمجة التطبيقات" في "كتب Google"

يعرض مستكشف واجهات برمجة التطبيقات بشكل تلقائي كيفية استخدام cURL لتنفيذ طلبك. ويمكن أن تعرض بعض واجهات برمجة التطبيقات أيضًا نماذج للغات أخرى، مثل JavaScript وJava وPython.

تشغيل عيّنات التعليمات البرمجية محليًا

توضّح علامات التبويب التالية المتطلبات الأساسية والخطوات اللازمة لتشغيل نماذج الرموز. لتشغيل نماذج الرموز، عليك إنشاء بيانات اعتماد التفويض واستخدامها. للحصول على شرح حول كيفية إنشاء مشروع وإنشاء بيانات اعتماد، راجع مستندات واجهة برمجة تطبيقات Google الخاصة بك.

تعتمد بيانات الاعتماد على ما يلي، وذلك استنادًا إلى نوع البيانات (العامة أو الخاصة) التي تصل إليها الطريقة:

• بالنسبة إلى البيانات العلنية، تكون بيانات الاعتماد مفتاح واجهة برمجة تطبيقات.

• بالنسبة إلى البيانات الخاصة، تكون بيانات الاعتماد هي ملف client_secret.json يحتوي على معرِّف عميل OAuth 2.0 وسر العميل أو رمز الدخول OAuth 2.0.

عنوان cURL

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. في Cloud Console، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات.
3. في Cloud Console، يمكنك إنشاء بيانات اعتماد معرِّف عميل بروتوكول OAuth لتطبيق ويب واستخدام https://developers.google.com/oauthplayground كعنوان URL لإعادة التوجيه.
4. في مساحة لعب OAuth 2.0، انقر على ضبط OAuth 2.0 .
5. ضع علامة في المربع استخدام بيانات الاعتماد الخاصة بك.
6. أدخِل معرِّف العميل وسر العميل الذي تم إنشاؤه في الخطوة 3.
7. في حقل النطاقات، اكتب النطاق المطلوب استخدامه مع طريقتك وانقر على تفويض واجهات برمجة التطبيقات.
8. (اختياري) إذا ظهر لك مع شاشة تسجيل الدخول، اختَر الحساب المطلوب استخدامه.
9. (اختياري) إذا تم عرض شاشة التفويض، انقر على قبول.
10. انقر على رمز تفويض Exchange للرموز المميزة. يتم عرض رمز مميز.
11. في نموذج رمز cURL، استبدِل [YOUR_API_KEY] بمفتاح واجهة برمجة التطبيقات الذي تم إنشاؤه في الخطوة 2: 'https://www.googleapis.com/drive/v3/files?key=[YOUR_API_KEY]' \
12. في نموذج رمز 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

ملاحظة: يصبح رمز الدخول قديمًا بعد 3600 ثانية. للحصول على رمز مميز جديد في "مساحة لعب OAuth 2.0"، انقر على إعادة تحميل رمز الدخول.

JavaScript

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. في Cloud Console، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات.
3. في وحدة تحكم السحابة الإلكترونية، أنشئ بيانات اعتماد معرِّف عميل OAuth لـ "Application;Web;application&quot، واضبط أصول JavaScript المصرَّح بها لتحديد عنوان URL الذي سترسل منه طلبات، مثل http://localhost.
4. انسخ نموذج الرمز الكامل إلى ملف محلي يمكن الوصول إليه من قِبل خادم الويب، مثل /var/www/html/example.html.

5. ابحث عن السطر في نموذج الرمز الذي يضبط مفتاح واجهة برمجة التطبيقات أو معرِّف العميل واستبدل القيمة بالقيم التي تم إنشاؤها في الخطوتين 2 و3:

   • مفتاح واجهة برمجة التطبيقات: gapi.client.setApiKey(YOUR_API_KEY);
   • معرّف عميل OAuth 2.0: gapi.client.init({ 'clientId': 'YOUR_CLIENT_ID',

تنفيذ نموذج الرمز

1. افتح الملف في المتصفّح الذي تستخدمه، مثل http://localhost/example.html. نقترح عليك استخدام متصفّح مع وحدة تحكّم تصحيح أخطاء، مثل Google Chrome.
2. (اختياري) إذا ظهر لك مع شاشة تسجيل الدخول، اختَر الحساب المطلوب استخدامه.
3. (اختياري) إذا تم عرض شاشة التفويض، انقر على قبول. يجب أن تعرض وحدة تصحيح الأخطاء استجابة الطريقة ككائن JSON.

Java

المتطلبات الأساسية

• Java 1.7 أو إصدار أحدث.
• الحصّة رقم 7 أو أكثر.

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
3. اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
4. إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه client_secret_CLIENTID.json، حيث يكون CLIENTID هو معرِّف العميل لمشروعك.

5. في دليل العمل، شغِّل الأوامر التالية لإنشاء بنية مشروع جديدة:

   $ gradle init --type basic
   $ mkdir -p src/main/java src/main/resources
   

6. وإذا أنشأت معرِّف عميل OAuth 2.0 في الخطوة 2، أعِد تسمية ملف JSON الذي نزَّلته إلى client_secret.json.

7. احفظ الملف الذي تمت إعادة تسميته في دليل src/main/resources الذي أنشأته في الخطوة 5.

8. في دليل العمل، افتح ملف 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
   }
   

9. في ملف 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
  

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
3. اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
4. إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه client_secret_CLIENTID.json، حيث يكون CLIENTID هو معرِّف العميل لمشروعك.
5. انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي 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
  

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
3. اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
4. إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه client_secret_CLIENTID.json، حيث يكون CLIENTID هو معرِّف العميل لمشروعك.
5. انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي YOUR_API_KEY، وموقع ملف أسرار العميل هو YOUR_CLIENT_SECRET_FILE.json.

تنفيذ نموذج الرمز

استخدِم الأمر التالي لتشغيل المثال:

  python sample.py

تطبع معظم النماذج ردًا من واجهة برمجة التطبيقات (أو شيء آخر) على STDOUT.

Ruby

المتطلبات الأساسية

• الإصدار 2.0 أو الإصدارات الأحدث من Ruby

• مكتبة عميل Google APIs لخدمة Ruby:

  gem install google-api-client`
  

الإعداد

1. اتبع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع أو اختياره لتطبيقك وتفعيل واجهة برمجة التطبيقات.
2. استنادًا إلى نوع البيانات التي تصل إليها الطريقة، يمكنك إنشاء مفتاح واجهة برمجة تطبيقات (بيانات عامة) أو إنشاء معرِّف عميل OAuth 2.0 (بيانات خاصة).
3. اضبط نوع التطبيق على تطبيق متوافق مع الكمبيوتر المكتبي.
4. إذا أنشأت معرِّف عميل OAuth 2.0، نزِّل ملف JSON الذي يحتوي على بيانات اعتماد OAuth 2.0. يشبه هذا الملف اسمًا يشبه client_secret_CLIENTID.json، حيث يكون CLIENTID هو معرِّف العميل لمشروعك.
5. انسخ نموذج الرمز إلى ملف محلي وعدِّل النموذج لتعريف مفتاح واجهة برمجة التطبيقات أو ملف أسرار العميل بشكل صحيح. في النموذج، قيمة مفتاح واجهة برمجة التطبيقات هي 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 لا يتم طلبه إلا بعد تحميل مكتبة العميل.