تتوفّر الآن إضافات Google Classroom بشكل عام للمطوّرين. يُرجى الاطّلاع على مستندات الإضافات للحصول على مزيد من المعلومات.

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

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

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

في ما يلي النقاط الثلاث التي يجب مراعاتها عند استخدام ميزات المعاينة مقارنةً بواجهة برمجة التطبيقات الثابتة v1:

يجب أن يكون مشروع Google Cloud المُرسِل مسجَّلاً في Google Workspace برنامج معاينة المطوّرين وأن يكون مُدرَجًا في القائمة المسموح بها من قِبل Google.
لا يتم عرض ميزات واجهة برمجة التطبيقات في برامج الاستخدام التجريبي أو الاستخدام التجريبي المحدود في مكتبات العميل المعيارية، وقد لا يكون بالإمكان الوصول إليها تلقائيًا عبر بروتوكول HTTP.
في أي وقت، قد تكون هناك حالات أو إصدارات متعددة لواجهة برمجة التطبيقات في مرحلة المحاولة.

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

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

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

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

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

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

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

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

https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY

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

لإنشاء مكتبة Python وإنشاء مثيل لخدمة Classroom باستخدام methods preview، يمكنك تحديد عنوان URL لـ Discovery باستخدام الخدمة المناسبة وبيانات الاعتماد والعلامة:

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 Developer Preview Program الأخرى. بالنسبة إلى المعاينات الخاصة، يُرجى التواصل مع جهة الاتصال التي تتعامل معها في Google إذا كنت بحاجة إلى إنشاء مكتبات ثابتة.

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

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

يتم تحديد إصدار من خلال ضبط الحقل PreviewVersion في الطلبات. على سبيل المثال، لإنشاء مقياس باستخدام واجهة برمجة التطبيقات Rubrics CRUD preview API، عليك ضبط 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 لخدمة Rubrics مع تصنيف مستوى العرض المناسب وإصدار المعاينة:

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.

لغة برمجة تطبيقات Google

من الممكن طلب واجهات برمجة التطبيقات لمعاينة المحتوى من "برمجة تطبيقات Google". ومع ذلك، هناك بعض الاختلافات عن الاستخدام المعتاد لخدمة Apps Script.

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

اطّلِع على الدليل السريع المقابل للتعرّف على IDE Apps Script وإعداد مشروع أساسي. بعد ذلك، اتّبِع هذه التعليمات للبدء في الاتصال بواجهات برمجة التطبيقات في مرحلة المعاينة:

تغيير مشروع Cloud المستخدَم في النص البرمجي

في إعدادات المشروع، انقر على تغيير المشروع وأدخِل رقم تعريف مشروع Cloud لأي مشروع سجّلته في برنامج معاينة المطوّرين (بشكل تلقائي، تستخدم النصوص البرمجية لبرمجة التطبيقات مشروعًا عامًا). لا يمكن إلا للمشاريع المُدرَجة استدعاء طرق المعاينة.

ضبط طلبات HTTP

بعد ذلك، اضبط طلب HTTP للطريقة التي تريد طلبها مجددًا في أداة التعديل. على سبيل المثال، في البدء السريع، تظهر قوائم الدورات التدريبية باستخدام خدمة Classroom على النحو التالي:

function listCourses() {
  try {
    const response = Classroom.Courses.list();
    const courses = response.courses;
    if (!courses || courses.length === 0) {
      console.log('No courses found.');
      return;
    }
    for (const course of courses) {
      console.log('%s (%s)', course.name, course.id);
    }
  } catch (err) {
    // TODO: Developer to handle.
    console.log(err.message);
  }
}

العملية المكافئة باستخدام HTTP مباشرةً هي:

function listCourses() {
  const response = UrlFetchApp.fetch(
        'https://classroom.googleapis.com/v1/courses', {
        method: 'GET',
        headers: {'Authorization': 'Bearer ' + ScriptApp.getOAuthToken()},
        contentType: 'application/json',
      });
  const data = JSON.parse(response.getContentText());
  if (data.error) {
    // TODO: Developer to handle.
    console.log(err.message);
    return;
  }
  if (!data.courses || !data.courses.length) {
    console.log('No courses found.');
    return;
  }
  for (const course of data.courses) {
    console.log('%s (%s)', course.name, course.id);
  }
}

عند استخدام "الخدمات المتقدّمة"، يتم استنتاج نطاقات OAuth المطلوبة، ولكن لإجراء طلبات HTTP مباشرة إلى Google APIs في "برمجة تطبيقات Google"، عليك إضافة النطاقات المناسبة يدويًا.

في إعدادات المشروع، فعِّل عرض ملف البيان "appsscript.json" في المحرِّر. ارجع إلى المحرِّر، وأضِف oauthScopes إلى ملف appscript.json لأيّ نطاق تحتاج إليه. يتم إدراج نطاقات طريقة معيّنة في صفحة المرجع. على سبيل المثال، يمكنك الاطلاع على صفحة طريقة قائمةcourses.courseWork.rubrics.

قد يبدو ملف appscript.json المعدَّل على النحو التالي:

{
  "timeZone": "America/Los_Angeles",
  "dependencies": {
  },
  "exceptionLogging": "STACKDRIVER",
  "runtimeVersion": "V8",
  "oauthScopes": [
    "https://www.googleapis.com/auth/script.external_request",
    "https://www.googleapis.com/auth/classroom.coursework.students",
    "https://www.googleapis.com/auth/classroom.courses",
    "https://www.googleapis.com/auth/spreadsheets.readonly",
    "https://www.googleapis.com/auth/spreadsheets"
  ]
}

توفير تسمية وإصدار معاينة

في النص البرمجي، تأكَّد من إضافة التصنيف المناسب وإصدار المعاينة كما هو موضّح في قسم HTTP السابق. سيظهر مثال طلب LIST المُرسَل إلى خدمة Rubrics على النحو التالي:

function listRubrics() {
  const courseId = COURSE_ID;
  const courseWorkId = COURSE_WORK_ID;
  const response = UrlFetchApp.fetch(
         `https://classroom.googleapis.com/v1/courses/${courseId}/courseWork/${courseWorkId}/rubrics?previewVersion=V1_20231110_PREVIEW`, {
        method: 'GET',
        headers: {
          'Authorization': 'Bearer ' + ScriptApp.getOAuthToken(),
          'X-Goog-Visibilities': 'DEVELOPER_PREVIEW'
        },
        contentType: 'application/json',
        muteHttpExceptions: true
      });
  const data = JSON.parse(response.getContentText());
  console.log(data)
  if (data.error) {
    // TODO: Developer to handle.
    console.log(error.message);
    return;
  }
  if (!data.rubrics || !data.rubrics.length) {
    console.log('No rubrics for this coursework!');
    return;
  }
  console.log(data.rubrics);
}