روش‌های API در برنامه‌های دسترسی اولیه یا پیش‌نمایش خصوصی خصوصی هستند، به این معنی که در کتابخانه‌های سرویس گیرنده استاندارد نمایش داده نمی‌شوند و ممکن است به‌طور پیش‌فرض از طریق HTTP در دسترس نباشند. این صفحه نحوه دسترسی به این روش های پیش نمایش را توضیح می دهد.
این سند چهار گزینه را برای مصرف API پیش‌نمایش مورد بحث قرار می‌دهد:
- کتابخانه های مشتری ثابت ارائه شده توسط Google.
- کتابخانه های مشتری ایجاد شده به صورت پویا
- درخواست های مستقیم HTTP
- کتابخانه مشتری سفارشی شما
استفاده از کتابخانه های ایستا یا پویا ایجاد شده توسط Google، روش توصیه شده برای استفاده از API است.
کتابخانه های ایستا
کتابخانه های کلاینت در زبان هایی مانند جاوا، Node.js، PHP و C# باید از منبع ساخته شوند. این کتابخانه ها در دانلودهای کتابخانه های سرویس گیرنده برای شما ارائه شده اند و روش های پیش نمایش را از قبل دارند.
ممکن است لازم باشد پیکربندی وابستگی‌های معمولی خود را برای استفاده از این کتابخانه‌های محلی به جای وارد کردن کتابخانه‌های مشتری استاندارد، که روش‌های پیش‌نمایش ندارند، تغییر دهید.
به عنوان مثال، اگر از 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-addons": "file:./googleapis-classroom-1.0.4.tgz"
}
}
سپس در برنامه خود، علاوه بر وابستگی های معمولی، ماژول classroom-with-addons را نیز بخواهید و سرویس classroom را از آن ماژول نمونه سازی کنید:
const {authenticate} = require('@google-cloud/local-auth');
const {google} = require('googleapis');
const classroomWithAddons = require('classroom-with-addons');
...
const classroom = classroomWithAddons.classroom({
version: 'v1',
auth: auth,
});
...
کتابخانه های پویا
کتابخانه‌های زبان‌هایی مانند پایتون، کتابخانه مشتری را در زمان اجرا با استفاده از یک سند کشف از سرویس 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>
برای تولید کتابخانه Python و نمونه سازی سرویس Classroom با متدهای افزودنی، می توانید URL Discovery را با سرویس، اعتبار و برچسب مناسب مشخص کنید:
classroom_service_with_rubrics = googleapiclient.discovery.build(
serviceName="classroom",
version="v1",
credentials=credentials,
static_discovery=False,
discoveryServiceUrl=f"https://classroom.googleapis.com/$discovery/rest?labels=ADD_ONS_ALPHA&key=ABCXYZ")
برای جزئیات بیشتر در مورد هر زبان ، اسناد کتابخانه مشتری Google API را مشاهده کنید. تمایز مهم برای کار با API های پیش نمایش، تعیین label مناسب است. در این پیش نمایش آن برچسب ADD_ONS_ALPHA است.
درخواست های HTTP
اگر درخواست‌های HTTP را بدون کتابخانه مشتری انجام می‌دهید، حتماً برچسب ( ADD_ONS_ALPHA ) را به‌عنوان سربرگ X-Goog-Visibilities اضافه کنید.
به عنوان مثال، برای مشاهده تمام پیوست های ایجاد شده توسط یک افزونه در زیر یک پست، از درخواست curl زیر استفاده کنید:
curl \
'https://classroom.googleapis.com/v1/courses/[courseId]/courseWork/[itemId]/addOnAttachments?key=[YOUR_API_KEY]' \
--header 'X-Goog-Visibilities: ADD_ONS_ALPHA' \
--header 'Authorization: Bearer [YOUR_ACCESS_TOKEN]' \
--header 'Accept: application/json' \
--compressed
API برای هر درخواست HTTP در مستندات REST توضیح داده شده است.
کتابخانه های مشتری سفارشی
اگر نیاز به ساخت کتابخانه خود دارید، به ساخت کتابخانه های مشتری مراجعه کنید. ایجاد کتابخانه خود خارج از محدوده این راهنما است، اما باید بخش کتابخانه‌های پویا را مرور کنید تا با برچسب‌های پیش‌نمایش و نقش آن‌ها در Discovery آشنا شوید.