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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ضبط طلبات 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 في Apps Script، عليك إضافة النطاقات المناسبة يدويًا.

في إعدادات المشروع، فعِّل عرض ملف البيان "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);
}