معاينة طرق الاستخدام التجريبي للإضافات

تكون طُرق واجهات برمجة التطبيقات في برامج الاستخدام التجريبي أو برامج المعاينة الخاصة خاصة، ما يعني أنّها لا تظهر في مكتبات العميل العادية وقد يتعذّر الوصول إليها تلقائيًا عبر بروتوكول HTTP. تصف هذه الصفحة كيف يمكنك الوصول إلى طرق المعاينة هذه.

يناقش هذا المستند أربعة خيارات لاستخدام واجهة برمجة التطبيقات الخاصة بالمعاينة:

  1. مكتبات العملاء الثابتة التي توفّرها Google
  2. مكتبات العملاء التي تم إنشاؤها ديناميكيًا.
  3. طلبات HTTP المباشرة.
  4. مكتبة برامجك المخصصة.

إنّ استخدام المكتبات الثابتة أو التي يتم إنشاؤها ديناميكيًا التي توفّرها Google هي الطريقة المقترَحة لاستخدام واجهة برمجة التطبيقات.

المكتبات الثابتة

يجب إنشاء مكتبات العملاء بلغات مثل Java وNode.js وPHP وC# من المصدر. تتوفّر هذه المكتبات لك ضمن عمليات تنزيل مكتبات العملاء، وتتوفّر طرق معاينة فيها حاليًا.

وقد تحتاج إلى تعديل إعدادات التبعيات النموذجية لاستخدام هذه المكتبات المحلية بدلاً من استيراد مكتبات العملاء العادية التي لا تتضمّن طُرق المعاينة.

على سبيل المثال، إذا كنت تستخدم Node.js وnpm، أضِف تنزيل مكتبة عميل Node.js (googleapis-classroom-1.0.4.tgz) كتبعية محلية في package.json:

{
  "name": "nodejs-classroom-example",
  "version": "1.0.0",
  ...
  "dependencies": {
    "@google-cloud/local-auth": "^2.1.0",
    "googleapis": "^95.0.0",
    "classroom-with-addons": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

بعد ذلك، اطلب في تطبيقك الوحدة classroom-with-addons بالإضافة إلى العناصر الاعتمادية العادية، وقم بإنشاء مثيل لخدمة classroom من تلك الوحدة:

const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithAddons = require('classroom-with-addons');

...

const classroom = classroomWithAddons.classroom({
  version: 'v1',
  auth: auth,
});

...

المكتبات الديناميكية

تنشئ المكتبات بلغات مثل Python مكتبة البرامج في وقت التشغيل باستخدام مستند اكتشاف من خدمة الاكتشاف.

مستند Discovery هو مواصفات يمكن للآلة قراءتها لوصف واجهات برمجة تطبيقات REST واستخدامها. وتُستخدَم في إنشاء مكتبات برامج ومكوّنات إضافية لبيئات IDE وأدوات أخرى تتفاعل مع Google APIs. قد توفر خدمة واحدة مستندات اكتشاف متعددة.

يمكن العثور على مستندات Discovery لخدمة Classroom API (classroom.googleapis.com) في نقطة النهاية التالية:

  • https://classroom.googleapis.com/$discovery/rest?labels=<PREVIEW_LABEL>&version=v1&key=<API key>

لإنشاء مكتبة Python وإنشاء مثيل لخدمة Classroom باستخدام طرق الإضافات، يمكنك تحديد عنوان URL للاكتشاف مع الخدمة وبيانات الاعتماد والتصنيف المناسبة:

classroom_service_with_rubrics = googleapiclient.discovery.build(
  serviceName="classroom",
  version="v1",
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=ADD_ONS_ALPHA&key=ABCXYZ")

يمكنك الاطّلاع على مستندات مكتبة عملاء Google API الفردية للحصول على تفاصيل حول كل لغة. يتمثل الفارق المهم للعمل مع واجهات برمجة تطبيقات المعاينة في تحديد label المناسب. في هذه المعاينة، هذا التصنيف هو ADD_ONS_ALPHA.

طلبات HTTP

إذا أجريت طلبات HTTP بدون مكتبة برامج، احرص على تضمين التصنيف (ADD_ONS_ALPHA) في شكل عنوان X-Goog-Visibilities.

على سبيل المثال، لعرض جميع المرفقات التي تم إنشاؤها بواسطة إضافة ضمن مشاركة، استخدِم طلب curl التالي:

curl \
  'https://classroom.googleapis.com/v1/courses/[courseId]/posts/[postId]/addOnAttachments?key=[YOUR_API_KEY]' \
  --header 'X-Goog-Visibilities: ADD_ONS_ALPHA' \
  --header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
  --header 'Accept: application/json' \
  --compressed

يتم وصف واجهة برمجة التطبيقات لكل طلب HTTP في مستندات REST.

مكتبات العملاء المخصّصة

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