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

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

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

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

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

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

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

إنّ استخدام المكتبات الثابتة التي يتم إنشاؤها ديناميكيًا أو التي تقدّمها 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 ‎(طرق) المعاينة، يمكنك تحديد عنوان 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 (راجِع مستندات مرجع label لواجهة برمجة التطبيقات الفردية المناسبة). بالنسبة إلى المعاينات المتاحة للجميع، يكون التصنيف 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.

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

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

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

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

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);
  }
}

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);
  }
}

{
  "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"
  ]
}

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);
}