Önizleme API'lerine erişme

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:

1. 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.
2. 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:

1. Dinamik olarak oluşturulmuş istemci kitaplıkları
2. Google tarafından sağlanan statik istemci kitaplıkları
3. 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()

Not: Özellikler v1 API'de genel kullanılabilirlik için doğrulanırken önizleme sürümlerinin geçici olarak kullanılması amaçlanmıştır. Desteğin sonlandırılmasından sonra önizleme sürümü davranışı değişebilir. Daha fazla bilgi için Classroom API Yol Haritası başlıklı makaleyi inceleyin.

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",
  ...
}

Not: Bir kaynakla ilişkilendirilen önizleme sürümü, kaynağı almak için kullanılan sürüme karşılık gelir. Kaynağı oluşturma çağrısı olması gerekmez. Yeni bir sürüm belirterek ileride GET, LIST veya PATCH çağrısı yaptıysanız yeni sürüm döndürülür.

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.