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

توضّح هذه الصفحة كيفية الوصول إلى ميزات الإصدار التجريبي من 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 واستخدامها. ويُستخدم لإنشاء مكتبات برامج العميل ومكوّنات IDE الإضافية وغيرها من الأدوات التي تتفاعل مع Google APIs. قد تقدّم الخدمة الواحدة مستندات استكشاف متعددة.

يمكن العثور على مستندات الاستكشاف الخاصة بخدمة 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 لمستند الاستكشاف مع الخدمة المناسبة وبيانات الاعتماد والتصنيف:

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 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 السابق.

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

تغيير مشروع على السحابة الإلكترونية الذي يستخدمه النص البرمجي

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

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

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