تمت ترجمة هذه الصفحة بواسطة Cloud Translation API‏.

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

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

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

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

تشغيل عيّنات الرموز البرمجية على الجهاز

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

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

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

cURL

الإعداد

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

الإعداد

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

الإعداد

اتّبِع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع لتطبيقك أو اختياره وتفعيل واجهة برمجة التطبيقات.
استنادًا إلى نوع البيانات التي تصل إليها الطريقة، أنشئ مفتاح API (البيانات العامة) أو أنشئ معرّف عميل 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 Analytics:
```
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 هو إصدار واجهة برمجة التطبيقات المدرَج لواجهة برمجة التطبيقات أسفل اسم واجهة برمجة التطبيقات في صفحة "واجهات برمجة تطبيقات 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
```

الإعداد

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

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

‫PHP 5.4 أو إصدار أحدث مع واجهة سطر الأوامر (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 أو الإصدار 3.5 من لغة Python أو الإصدارات الأحدث
أداة إدارة الحِزم 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
```

الإعداد

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

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

Ruby 2.0 أو إصدار أحدث
مكتبة برامج Google API للغة Ruby:
```
gem install google-api-client`
```

الإعداد

اتّبِع التعليمات الواردة في مستندات واجهة برمجة التطبيقات لإنشاء مشروع لتطبيقك أو اختياره وتفعيل واجهة برمجة التطبيقات.
استنادًا إلى نوع البيانات التي تصل إليها الطريقة، أنشئ مفتاح API (البيانات العامة) أو أنشئ معرّف عميل 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 Endpoints وكنت تشغّل نقطة النهاية في خادم تطوير، قد يعرض المتصفّح تحذيرًا بشأن المحتوى المختلط. يظهر هذا التحذير لأنّ "مستكشف واجهات برمجة التطبيقات" يتم تحميله عبر 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 API لتطبيقات JavaScript قبل تحميل المكتبة. تأكَّد من عدم استدعاء الرمز البرمجي الذي يشير إلى المتغيّر gapi إلا بعد loading مكتبة العميل.