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

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

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

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

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

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

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

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

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

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

ملاحظة: من المفترض أن تكون إصدارات المعاينة مؤقتة أثناء التحقّق من صحة الميزات. للتوافر العام في واجهة برمجة التطبيقات v1. يخضع سلوك إصدار المعاينة إلى التغيير بعد فترة الإيقاف النهائي. اطّلِع على خطة تحقيق أهداف Classroom API للحصول على مزيد من المعلومات.

تحتوي الموارد المرتبطة باستدعاء طريقة المعاينة أيضًا على يتم استخدام 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",
  ...
}

ملاحظة: يتوافق إصدار المعاينة المرتبط بالمورد مع الإصدار. يُستخدم لاسترداد المورد، وليس بالضرورة طلب إنشاء المورد المصدر؛ إذا أجريت مكالمة في المستقبل عبر GET أو LIST أو PATCH باستخدام إصدار جديد المحدد، فسيتم عرض الإصدار الجديد.

طلبات 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_WORK_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_WORK_ID/rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY&previewVersion=V1_20231110_PREVIEW' \
  --header 'X-Goog-Visibilities: DEVELOPER_PREVIEW' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]"}' \
  --compressed

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