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

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

لوحة ملء الشاشة في "مستكشف واجهات برمجة التطبيقات" الخاصة بواجهة Google Books API
الشكل 2: لوحة مستكشف واجهات برمجة التطبيقات في وضع ملء الشاشة لواجهة كتب Google API.

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

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

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

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

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

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

cURL

الإعداد

  1. اتّبِع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع لتطبيقك أو اختياره وتفعيل واجهة برمجة التطبيقات.
  2. في وحدة تحكّم السحابة الإلكترونية، أنشِئ مفتاح واجهة برمجة تطبيقات.
  3. في وحدة تحكّم السحابة الإلكترونية، أنشِئ بيانات اعتماد معرّف عميل OAuth لتطبيق ويب واستخدِم https://developers.google.com/oauthplayground كعنوان URI لإعادة التوجيه.
  4. في مساحة بروتوكول OAuth 2.0، انقر على إعدادات OAuth 2.0 Configuration .
  5. ضَع علامة في المربّع استخدام بيانات الاعتماد الخاصة بك.
  6. أدخِل معرّف العميل وسر العميل اللذين تم إنشاؤهما في الخطوة 3.
  7. في حقل النطاقات، اكتب النطاق الذي تريد استخدامه مع طريقتك وانقر على تفويض واجهات برمجة التطبيقات.
  8. (اختياري) إذا ظهرت شاشة "تسجيل الدخول"، اختَر الحساب الذي تريد استخدامه.
  9. (اختياري) إذا ظهرت شاشة التفويض، انقر على قبول.
  10. انقر على تبديل رمز التفويض بالرموز المميّزة. يتم عرض رمز مميّز.
  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

JavaScript

الإعداد

  1. اتّبِع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع لتطبيقك أو اختياره وتفعيل واجهة برمجة التطبيقات.
  2. في وحدة تحكّم السحابة الإلكترونية، أنشِئ مفتاح واجهة برمجة تطبيقات.
  3. في وحدة تحكّم السحابة الإلكترونية، أنشِئ بيانات اعتماد معرّف عميل OAuth لـ "تطبيق ويب" واضبط صفحات 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.

جافا

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

  • الإصدار 1.7 من Java أو إصدار أحدث
  • الإصدار 7 من Gradle أو إصدار أحدث

الإعداد

  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 Analytics API:

    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 APIs المتوافقة. ينقلك رابط الإصدار إلى GitHub. يظهر اسم واجهة برمجة التطبيقات في أعلى منتصف الصفحة ويسبقه googleapis/google-apis-services-. على سبيل المثال، بالنسبة إلى الإصدار 3 من Drive API، يكون API_NAME هو drive.
  • API_VERSION هو إصدار واجهة برمجة التطبيقات المُدرَج لواجهة برمجة التطبيقات أسفل اسم واجهة برمجة التطبيقات في صفحة واجهات برمجة التطبيقات المتوافقة من Google.
  • REVISION هو رقم المراجعة المُدرَج في مرجع JavaDoc لواجهة برمجة التطبيقات. يمكن العثور على مرجع JavaDoc على 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
  • أداة إدارة التبعيات Composer مثبَّتة على مستوى العالم

  • مكتبة عميل Google APIs للغة PHP:

    • إذا لم يسبق لك تثبيت مكتبة البرامج، نفِّذ الأمر:

      composer require google/apiclient:^2.0

    • إذا سبق لك تثبيت مكتبة البرامج، ننصحك بتحديثها للتأكّد من حصولك على أحدث الفئات لمكتبة البرامج التي تختبرها. لتحديث مكتبة البرامج، نفِّذ الأمر:

      composer update google/apiclient --with-dependencies

تنفيذ عيّنة التعليمات البرمجية

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

  php sample.php

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

Python

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

  • الإصدار 2.7 من Python أو الإصدار 3.5 أو إصدار أحدث
  • أداة إدارة الحِزم pip

  • مكتبة عميل 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، ولكن بنطاق ضيق جدًا.
  • عند إعداد مفتاح واجهة برمجة التطبيقات، يمكنك إعداد قيود لمنع الاستخدام غير المصرّح لبيانات اعتمادك. ومع ذلك، لا يستوفي الطلب هذه القيود. لمزيد من المعلومات، يُرجى الرجوع إلى مقالة استخدام قيود مفتاح واجهة برمجة التطبيقات.

تلقّيت تحذيرًا بشأن المحتوى المختلط

إذا كنت تستخدم نقاط النهاية في السحابة الإلكترونية وتشغِّل نقطة النهاية في خادم تطوير، قد يعرض متصفّحك تحذيرًا بشأن المحتوى المختلط. يظهر هذا التحذير لأنّ مستكشف واجهات برمجة التطبيقات يتم تحميله عبر 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

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