واجهات برمجة التطبيقات لمعاينة التطبيقات

توضّح هذه الصفحة كيفية الوصول إلى ميزات معاينة Classroom API وتحديد إصدارات المعاينة.

هناك اعتباران عند استخدام ميزات المعاينة عند مقارنتهما بواجهة برمجة التطبيقات الإصدار 1 الثابتة، وهما:

  1. لا يتم عرض ميزات واجهة برمجة التطبيقات في برامج الاستخدام التجريبي أو المعاينة في مكتبات العملاء العادية، وقد لا يمكن الوصول إليها تلقائيًا عبر HTTP.
  2. في أي وقت، قد تكون هناك حالات أو إصدارات متعددة لواجهة برمجة التطبيقات في المعاينة.

تفعيل ميزات المعاينة في مكتبات العميل

أحد الخيارات الشائعة لاستخدام Classroom API هو استخدام مكتبة البرامج. هناك ثلاثة أنواع من مكتبات العملاء:

  1. مكتبات العملاء التي تم إنشاؤها ديناميكيًا
  2. مكتبات العملاء الثابتة التي تقدّمها Google
  3. مكتبة العملاء المخصصة الخاصة بك

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

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

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

مستند 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

أهم ما يميّز العمل باستخدام واجهات برمجة التطبيقات للمعاينة هو تحديد label المناسب. بالنسبة إلى المعاينات العلنية في Classroom، يكون التصنيف هو DEVELOPER_PREVIEW.

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

classroom_service_with_preview_features = googleapiclient.discovery.build(
  serviceName='classroom',
  version='v1',
  credentials=credentials,
  static_discovery=False,
  discoveryServiceUrl='https://classroom.googleapis.com/$discovery/rest?labels=DEVELOPER_PREVIEW&key=API_KEY)'

يمكنك الاطّلاع على مستندات مكتبة برامج Google API الفردية للحصول على تفاصيل حول كل لغة.

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

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

بالنسبة إلى المعاينات العلنية، يمكن العثور على مكتبات عملاء Classroom من خلال مكتبات برامج "برنامج المعاينة للمطوّرين على Workspace" الأخرى. للمعاينات الخاصة، تواصَل مع جهة اتصال Google إذا كنت بحاجة إلى إنشاء مكتبات ثابتة.

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

على سبيل المثال، لاستخدام مكتبة برامج Go، عليك استخدام توجيه replace في ملف go.mod من أجل طلب وحدة من دليل محلي:

module example.com/app

go 1.21.1

require (
    golang.org/x/oauth2 v0.12.0
    google.golang.org/api v0.139.0 // Classroom library is in here.
)

require (
  ...
)

// Use a local copy of the Go client library.
replace google.golang.org/api v0.139.0 => ../google-api-go-client

كمثال آخر، إذا كنت تستخدم 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-preview-features": "file:./googleapis-classroom-1.0.4.tgz"
  }
}

بعد ذلك، اطلب في تطبيقك الوحدة classroom-with-preview-features بالإضافة إلى التبعيات العادية، أنشئ مثيلاً لخدمة classroom من هذه الوحدة:

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

...

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

...

تحديد إصدار لمعاينة واجهة برمجة التطبيقات

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

تم توثيق الإصدارات المختلفة والميزات التي تتضمنها في خارطة طريق واجهة برمجة تطبيقات Classroom. تصف الوثائق المرجعية للطرق والحقول أيضًا الإصدارات التي تتوفر فيها الطريقة أو الحقل.

ويتم تحديد إصدار من خلال ضبط الحقل PreviewVersion في الطلبات. على سبيل المثال، لإنشاء قاعدة تقييم باستخدام واجهة برمجة تطبيقات معاينة Rubrics CRUD، يمكنك ضبط previewVersion على V1_20231110_PREVIEW في طلب CREATE:

rubric = service.courses().courseWork().rubrics().create(
            courseId=course_id,
            courseWorkId=coursework_id,
            # Specify the preview version. Rubrics CRUD capabilities are
            # supported in V1_20231110_PREVIEW and later.
            previewVersion="V1_20231110_PREVIEW",
            body=body
).execute()

تحتوي أيضًا الموارد المرتبطة باستدعاء طريقة المعاينة على previewVersion المستخدم في المكالمة كحقل للقراءة فقط، لمساعدتك في معرفة الإصدار الذي تستخدمه. على سبيل المثال، تحتوي الاستجابة من استدعاء CREATE السابق على قيمة V1_20231110_PREVIEW:

print(json.dumps(rubric, indent=4))
{
  "courseId": "123",
  "courseWorkId": "456",
  "creationTime": "2023-10-23T18:18:29.932Z",
  "updateTime": "2023-10-23T18:18:29.932Z",
  "id": "789",
  "criteria": [...],
  # The preview version used in the call that returned this resource.
  "previewVersion": "V1_20231110_PREVIEW",
  ...
}

طلبات HTTP

من الممكن أيضًا استخدام Classroom API مباشرةً مع HTTP.

إذا أجريت طلبات HTTP بدون مكتبة برامج، ستظل بحاجة إلى تفعيل ميزات المعاينة التي تحدّد إصدار معاينة. ويتم ذلك من خلال إعداد label مع عنوان X-Goog-Visibilities وإصدار المعاينة المذكور أعلاه كمعلَمة طلب بحث أو حقل نص POST. في ما يتعلّق بالمعاينات العلنية، يكون التصنيف هو DEVELOPER_PREVIEW.

على سبيل المثال، يؤدي طلب curl التالي إلى إجراء استدعاء LIST لخدمة "قواعد التقييم" باستخدام تصنيف مستوى الرؤية وإصدار المعاينة المناسبَين:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID/rubrics?key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --compressed

يمكنك أيضًا تحديد إصدار المعاينة في نص الطلب، على سبيل المثال عند تقديم طلب POST:

curl --request PATCH \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

يتم توضيح واجهة برمجة التطبيقات لكل طلب HTTP في وثائق REST.