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

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

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

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

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

تشكّل مكتبة البرامج خيارًا شائعًا لاستخدام 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()

تحتوي الموارد المرتبطة باستدعاء طريقة المعاينة أيضًا على يتم استخدام 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 لخدمة قواعد التقييم باستخدام تصنيف مستوى الرؤية وإصدار المعاينة المناسب:

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

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 في "برمجة تطبيقات 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 إلى ستبدو خدمة قواعد التقييم على النحو التالي:

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