دسترسی به API های پیش نمایش

این صفحه نحوه دسترسی به ویژگی‌های پیش‌نمایش Classroom API و تعیین نسخه‌های پیش‌نمایش را شرح می‌دهد.

سه نکته‌ای که هنگام استفاده از ویژگی‌های پیش‌نمایش در مقایسه با API نسخه ۱ پایدار باید در نظر گرفته شوند عبارتند از:

1. پروژه‌ی مورد نظر برای توسعه‌دهندگان گوگل کلود باید در برنامه‌ی پیش‌نمایش توسعه‌دهندگان گوگل ورک‌اسپیس ثبت‌نام شده باشد و مجوز آن توسط گوگل فهرست شده باشد.
2. ویژگی‌های API در برنامه‌های دسترسی اولیه یا پیش‌نمایش در کتابخانه‌های استاندارد کلاینت نمایش داده نمی‌شوند و ممکن است به‌طور پیش‌فرض از طریق HTTP قابل دسترسی نباشند.
3. در هر زمان معین، ممکن است چندین حالت یا نسخه API در پیش‌نمایش وجود داشته باشد.

فعال کردن ویژگی‌های پیش‌نمایش در کتابخانه‌های کلاینت

یک گزینه رایج برای استفاده از Classroom API، استفاده از یک کتابخانه کلاینت است. سه نوع کتابخانه کلاینت وجود دارد:

1. کتابخانه‌های کلاینت تولید شده به صورت پویا
2. کتابخانه‌های کلاینت استاتیک ارائه شده توسط گوگل
3. کتابخانه کلاینت سفارشی خودتان

استفاده از کتابخانه‌های پویا یا کتابخانه‌های ایستا که توسط گوگل ارائه می‌شوند، روش پیشنهادی برای استفاده از API است. اگر نیاز به ساخت کتابخانه شخصی خود دارید، به بخش ساخت کتابخانه‌های کلاینت مراجعه کنید. ایجاد کتابخانه شخصی خارج از محدوده این راهنما است، اما باید بخش کتابخانه‌های پویا را مرور کنید تا در مورد برچسب‌های پیش‌نمایش و نقش آنها در اکتشاف اطلاعات کسب کنید.

کتابخانه‌های پویا

کتابخانه‌ها در زبان‌هایی مانند پایتون، کتابخانه کلاینت را در زمان اجرا با استفاده از یک سند کشف از سرویس کشف تولید می‌کنند.

یک سند اکتشاف، مشخصاتی قابل خواندن توسط ماشین برای توصیف و استفاده از APIهای REST است. از آن برای ساخت کتابخانه‌های کلاینت ، افزونه‌های IDE و سایر ابزارهایی که با APIهای گوگل تعامل دارند، استفاده می‌شود. یک سرویس ممکن است چندین سند اکتشاف ارائه دهد.

اسناد اکتشافی برای سرویس Classroom API ( classroom.googleapis.com ) را می‌توانید در نقطه پایانی زیر پیدا کنید:

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

نکته‌ی مهم در کار با پیش‌نمایش APIها، تعیین label مناسب است. برای پیش‌نمایش‌های عمومی Classroom، این برچسب DEVELOPER_PREVIEW است.

برای تولید کتابخانه پایتون و نمونه‌سازی سرویس Classroom با متدهای پیش‌نمایش، می‌توانید Discovery 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 مراجعه کنید.

کتابخانه‌های ایستا

کتابخانه‌های کلاینت در زبان‌هایی مانند جاوا، Node.js، PHP، C# و Go باید از منبع ساخته شوند. این کتابخانه‌ها برای شما ارائه شده‌اند و ویژگی‌های پیش‌نمایش از قبل در آنها گنجانده شده است.

برای پیش‌نمایش‌های عمومی، کتابخانه‌های کلاینت Classroom را می‌توان در کنار سایر کتابخانه‌های کلاینت برنامه پیش‌نمایش توسعه‌دهندگان Workspace پیدا کرد. برای پیش‌نمایش‌های خصوصی، در صورت نیاز به ایجاد کتابخانه‌های استاتیک، با مخاطب گوگل خود تماس بگیرید.

ممکن است لازم باشد پیکربندی وابستگی‌های معمول خود را تغییر دهید تا از این کتابخانه‌های محلی استفاده کنید، نه اینکه کتابخانه‌های استاندارد کلاینت را که ویژگی‌های پیش‌نمایش ندارند، وارد کنید.

برای مثال، برای استفاده از کتابخانه کلاینت 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 را نیز به آن نیاز (command) داشته باشید و سرویس 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,
});

...

نسخه پیش‌نمایش API را مشخص کنید

صرف نظر از اینکه از یک کتابخانه استاتیک یا پویا استفاده می‌کنید، هنگام فراخوانی API به متدهایی با قابلیت پیش‌نمایش، باید نسخه پیش‌نمایش را مشخص کنید.

نسخه‌های مختلف موجود و ویژگی‌هایی که شامل می‌شوند، در نقشه راه Classroom API مستند شده‌اند. مستندات مرجع برای متدها و فیلدها همچنین توضیح می‌دهند که متد یا فیلد در کدام نسخه(ها) موجود است.

مشخص کردن یک نسخه با تنظیم فیلد PreviewVersion در درخواست‌ها انجام می‌شود. برای مثال، برای ایجاد یک روبریک با API پیش‌نمایش CRUD روبریک، باید previewVersion در درخواست CREATE روی V1_20231110_PREVIEW تنظیم کنید:

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 انجام می‌شود (به مستندات مرجع API مربوطه مراجعه کنید). برای پیش‌نمایش‌های عمومی، برچسب 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

API مربوط به هر درخواست HTTP در مستندات REST شرح داده شده است.

اسکریپت برنامه‌های گوگل

فراخوانی APIهای پیش‌نمایش از Google Apps Script امکان‌پذیر است. با این حال، تفاوت‌های کمی با استفاده‌ی معمول از Apps Script وجود دارد.

1. شما باید اسکریپت خود را طوری پیکربندی کنید که از هر پروژه Google Cloud که در برنامه پیش‌نمایش توسعه‌دهندگان ثبت‌نام کرده‌اید، استفاده کند.
2. سرویس‌های پیشرفته از روش‌های پیش‌نمایش پشتیبانی نمی‌کنند، بنابراین باید درخواست‌ها را مستقیماً با HTTP ارسال کنید.
3. شما باید یک برچسب و نسخه پیش‌نمایش، همانطور که در بخش HTTP قبلی توضیح داده شد، ارائه دهید.

برای آشنایی با Apps Script و راه‌اندازی اولیه پروژه، به راهنمای سریع مربوطه مراجعه کنید. سپس برای شروع فراخوانی APIهای پیش‌نمایش، این دستورالعمل‌ها را دنبال کنید:

پروژه ابری مورد استفاده توسط اسکریپت را تغییر دهید

در تنظیمات پروژه ، روی تغییر پروژه کلیک کنید و شناسه پروژه ابری هر پروژه‌ای را که در برنامه پیش‌نمایش توسعه‌دهندگان ثبت‌نام کرده‌اید، وارد کنید (به‌طور پیش‌فرض، اسکریپت‌های Apps Script از یک پروژه عمومی استفاده می‌کنند). فقط پروژه‌های ثبت‌نام‌شده می‌توانند متدهای پیش‌نمایش را فراخوانی کنند.

پیکربندی درخواست‌های 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 به APIهای گوگل در Apps Script، باید محدوده‌های مناسب را به صورت دستی اضافه کنید.

در تنظیمات پروژه ، گزینه‌ی «نمایش فایل مانیفست برنامه‌ها در ویرایشگر» (Show "appsscript.json" manifest file in editor) را فعال کنید. به ویرایشگر برگردید و برای هر محدوده‌ای که نیاز دارید، 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);
}