Bu sayfada, Classroom API'nin önizleme özelliklerine nasıl erişebileceğiniz ve önizleme sürümlerini nasıl belirleyebileceğiniz açıklanmaktadır.
Kararlı v1 API ile karşılaştırıldığında önizleme özelliklerini kullanırken dikkat edilmesi gereken iki nokta şunlardır:
- Erken erişim veya önizleme programlarındaki API özellikleri, standart istemci kitaplıklarında sunulmaz ve varsayılan olarak HTTP üzerinden bu özelliklere erişilemeyebilir.
- Herhangi bir zamanda önizlemede birden fazla API durumu veya sürümü olabilir.
İstemci kitaplıklarında önizleme özelliklerini etkinleştir
Classroom API'yi kullanmak için yaygın olarak kullanılan bir seçenek, istemci kitaplığı kullanmaktır. Üç tür istemci kitaplığı vardır:
- Dinamik olarak oluşturulmuş istemci kitaplıkları
- Google tarafından sağlanan statik istemci kitaplıkları
- Kendi özel istemci kitaplığınız
API'nin kullanılması için dinamik olarak oluşturulmuş veya Google tarafından sağlanan statik kitaplıkların kullanılması önerilir. Kendi kitaplığınızı oluşturmanız gerekiyorsa istemci kitaplıkları oluşturma konusuna bakın. Kendi kitaplığınızı oluşturmak bu kılavuzun kapsamı dışındadır ancak önizleme etiketleri ve Keşif'teki rolleri hakkında bilgi edinmek için dinamik kitaplıklar bölümünü incelemeniz gerekir.
Dinamik kitaplıklar
Python gibi dillerdeki kitaplıklar, istemci kitaplığını Discovery hizmetinden bir Discovery Dokümanı kullanarak çalışma zamanında oluşturur.
Keşif Belgesi, REST API'lerini açıklamak ve kullanmak için makine tarafından okunabilir bir spesifikasyondur. İstemci kitaplıkları, IDE eklentileri ve Google API'leriyle etkileşimde bulunan diğer araçları oluşturmak için kullanılır. Bir hizmet, birden fazla keşif belgesi sağlayabilir.
Classroom API hizmeti (classroom.googleapis.com
) için Keşif Belgeleri aşağıdaki uç noktada bulunabilir:
https://classroom.googleapis.com/$discovery/rest?labels=PREVIEW_LABEL&version=v1&key=API_KEY
Önizleme API'leriyle çalışmaya ilişkin önemli ayrım, uygun label
belirtilmesidir. Classroom herkese açık önizlemeleri için bu etiket
DEVELOPER_PREVIEW
şeklindedir.
Python kitaplığını oluşturmak ve önizleme yöntemleriyle Classroom hizmetini örneklendirmek için Keşif URL'sini uygun hizmet, kimlik bilgileri ve etiketle belirtebilirsiniz:
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)'
Her dille ilgili ayrıntılar için ayrı Google API istemci kitaplığı belgelerine bakın.
Statik kitaplıklar
Java, Node.js, PHP, C# ve Go gibi dillerdeki istemci kitaplıkları kaynaktan derlenmelidir. Bu kitaplıklar sizin için sağlanır ve önizleme özellikleri hâlihazırda dahil edilmiştir.
Herkese açık önizlemeler için Classroom istemci kitaplıkları, diğer Workspace Geliştirici Önizleme Programı istemci kitaplıklarıyla birlikte bulunabilir. Gizli önizlemeler için statik kitaplıklar oluşturmanız gerekirse Google temsilcinizle iletişime geçin.
Önizleme özelliklerine sahip olmayan standart istemci kitaplıklarını içe aktarmak yerine, bu yerel kitaplıkları kullanmak için tipik bağımlılık yapılandırmanızı değiştirmeniz gerekebilir.
Örneğin, Go istemci kitaplığını kullanmak için yerel bir dizinden modül zorunlu kılmak üzere go.mod
dosyanızda replace
yönergesini kullanmanız gerekir:
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
Başka bir örnek olarak, Node.js ve npm kullanıyorsanız, Node.js istemci kitaplığı indirmesini (googleapis-classroom-1.0.4.tgz
) package.json
konumuna yerel bağımlılık olarak ekleyin:
{
"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"
}
}
Ardından uygulamanızda normal bağımlılıklara ek olarak classroom-with-preview-features
modülünü zorunlu kılın ve bu modülden classroom
hizmetini örnekleyin:
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,
});
...
Önizleme API'si sürümü belirtme
Statik veya dinamik kitaplık kullanmanız fark etmeksizin, önizleme özelliklerine sahip yöntemlere API çağrıları yaparken önizleme sürümünü belirtmeniz gerekir.
Kullanılabilen farklı sürümler ve içerdikleri özellikler Classroom API Yol Haritası'nda açıklanmıştır. Yöntemler ve alanlar için referans belgelerinde yöntemin veya alanın hangi sürümlerde kullanılabildiği de açıklanmaktadır.
Sürümlerin belirtilmesi, isteklerde PreviewVersion alanı ayarlanarak yapılır.
Örneğin, Rubrics CRUD önizleme API'siyle bir puan anahtarı oluşturmak için CREATE isteğinde previewVersion
değerini V1_20231110_PREVIEW
olarak ayarlarsınız:
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()
Bir önizleme yöntemi çağrısıyla ilişkilendirilen kaynaklar, hangi sürümü kullandığınızı anlamanıza yardımcı olmak için çağrıda salt okunur alan olarak previewVersion
öğesini de içerir. Örneğin, önceki CREATE çağrısının yanıtı V1_20231110_PREVIEW
değerini içerir:
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 istekleri
Classroom API'yi doğrudan HTTP ile kullanmak da mümkündür.
İstemci kitaplığı olmadan HTTP isteklerinde bulunsanız da bir önizleme sürümü belirtmek için önizleme özelliklerini etkinleştirmeniz gerekir. Bu, X-Goog-Visibilities
başlığına sahip bir label
, sorgu parametresi veya POST gövde alanı olarak önceden belirtilen önizleme sürümü ayarlanarak yapılır. Herkese açık önizlemeler için etiket
DEVELOPER_PREVIEW
şeklindedir.
Örneğin, aşağıdaki curl isteği, Puan Anahtarları hizmetine uygun görünürlük etiketi ve önizleme sürümüyle bir LIST çağrısı yapar:
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
Önizleme sürümünü istek gövdesinde de belirtebilirsiniz, örneğin bir POST isteği oluştururken:
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
Her HTTP isteğinin API'si REST dokümanlarında açıklanmıştır.