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

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

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

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

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

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

  1. کتابخانه های مشتری ایجاد شده به صورت پویا
  2. کتابخانه های مشتری ثابت ارائه شده توسط Google
  3. کتابخانه مشتری سفارشی شما

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

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

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

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

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

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

تمایز مهم برای کار با API های پیش نمایش، تعیین 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 پیدا کرد. برای پیش‌نمایش‌های خصوصی، اگر نیاز به ایجاد کتابخانه‌های ثابت دارید، با مخاطب 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,
});

...

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

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

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

تعیین یک نسخه با تنظیم فیلد PreviewVersion در درخواست ها انجام می شود. به عنوان مثال، برای ایجاد یک روبریک با Rubrics CRUD preview API، در درخواست CREATE، previewVersion را روی 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

همچنین امکان مصرف مستقیم API Classroom با HTTP وجود دارد.

اگر درخواست‌های HTTP را بدون کتابخانه مشتری انجام می‌دهید، همچنان باید ویژگی‌های پیش‌نمایش را فعال کنید تا یک نسخه پیش‌نمایش را مشخص کنید. این کار با تنظیم یک label با هدر X-Goog-Visibilities و نسخه پیش نمایش فوق الذکر به عنوان پارامتر پرس و جو یا فیلد بدنه POST انجام می شود. برای پیش‌نمایش‌های عمومی، برچسب DEVELOPER_PREVIEW است.

به عنوان مثال، درخواست curl زیر یک تماس LIST با سرویس Rubrics با برچسب دید مناسب و نسخه پیش نمایش برقرار می کند:

curl \
  'https://classroom.googleapis.com/v1/courses/COURSE_ID/courseWork/COURSE_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_ID//rubrics/RUBRIC_ID?updateMask=criteria&key=API_KEY' \
  --header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
  --header 'Accept: application/json' \
  --header 'Content-Type: application/json' \
  --data '{"criteria":"[...]", "preview_version": "V1_20231110_PREVIEW"}' \
  --compressed

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