Dokumentasi pembangun Lingara

Halaman ini diterjemahkan daripada bahasa Inggeris. Jika kedua-duanya berbeza, halaman bahasa Inggeris adalah yang betul. Baca halaman bahasa Inggeris

Sambungan terdiri daripada langkah, dan mana-mana langkah boleh membawa skrip. Skrip sesuatu langkah ialah badan sebuah fungsi. Ia menerima dua nilai: lingara, API pada halaman ini, dan input, medan langkah itu sendiri bersama kliennya dan langkah yang disambungkan sebelumnya. Jenis input bergantung pada jenis langkah, jadi skrip langkah webhook membaca medan langkah webhook. Skrip mengembalikan tepat satu objek, yang dibina oleh salah satu pembantu di bawah.

Skrip tidak pernah melihat rahsia. Di tempat sesuatu langkah memerlukan kliennya, ia mendapat pemegang, seperti input.client, dan pembantu merekodkan pemegang itu. Lingara mengisi nilai sebenar apabila anda menggunakan sambungan.

Apa yang tidak boleh dilakukan oleh skrip

Skrip berjalan dalam pelayar anda sendiri, dalam worker tanpa rangkaian dan tanpa storan. Ia tertakluk pada had berikut:

Ia selesai dalam masa 1 saat.
Rentetan yang dikembalikannya paling panjang 2048 aksara.
Senarai yang dikembalikannya mempunyai paling banyak 64 item.
Keseluruhan hasilnya paling besar 16 KiB.

Skrip yang melanggar had, melontar ralat, atau mengembalikan sesuatu selain hasil satu pembantu akan menggagalkan langkahnya, dan “Semaknya” memaparkan langkah mana dan sebabnya.

Janji versi

Semua pada halaman ini ialah lingara.v1. Dalam v1 API hanya berkembang: pembantu baharu, pilihan pilihan yang baharu atau jenis langkah baharu mungkin muncul, tetapi tiada apa-apa yang boleh anda gunakan hari ini akan dibuang, dinamakan semula atau disempitkan. Perubahan yang akan merosakkan skrip ialah versi baharu di sebelah versi ini, dan v1 kekal seperti sedia ada.

Pengisytiharan

Setiap pengisytiharan di bawah dijana daripada fail yang sama yang digunakan oleh editor skrip untuk melengkapkan kod.

`NodeHandle`

Id langkah lain, seperti "n1". Langkah yang bergantung menamakan kliennya melalui pemegang.

export type NodeHandle = string;

`Scope`

Kebenaran yang boleh dipegang oleh klien API. Pelayan menentukan kebenaran mana yang boleh digunakan oleh akaun anda.

export type Scope = 'vocab:generate' | 'lesson_plans:read' | 'lesson_plans:write' | 'tutor:converse' | 'usage:read' | 'events:read' | 'events:write' | 'embed:mint' | 'embed:play';

`AppSlot`

Tempat dalam aplikasi Lingara di mana kad sesebuah aplikasi boleh muncul.

export type AppSlot = 'plans.empty_detail' | 'home.side';

`ContextSlice`

Sebahagian daripada konteks pelajar yang boleh diminta oleh aplikasi untuk diterima.

export type ContextSlice = 'languages' | 'plan_summary' | 'review_due' | 'tutor_topic';

`ClientOptions`

Pilihan untuk lingara.client.

export interface ClientOptions {
    name: string;
    scopes: readonly Scope[];
    redirectUris?: readonly string[];
}

name (string) — Nama klien, seperti yang dipaparkan oleh Alat pembangun.
scopes (readonly Scope[]) — Kebenaran yang diminta oleh klien.
redirectUris? (readonly string[]) — Tempat aliran kod kebenaran boleh menghantar pelajar kembali. Tinggalkan untuk klien pelayan-ke-pelayan.

`WebhookOptions`

Pilihan untuk lingara.webhook.

export interface WebhookOptions {
    client: NodeHandle;
    url: string;
    events: readonly string[];
}

client (NodeHandle) — Langkah klien yang memiliki webhook ini: input.client.
url (string) — Alamat HTTPS tempat Lingara menghantar acara.
events (readonly string[]) — Jenis acara yang hendak dihantar, seperti "lesson_plan.ready".

`ManifestOptions`

Pilihan untuk lingara.manifest, dalam camelCase; pembantu menulis bentuk wayar manifes.

export interface ManifestOptions {
    name: string | Readonly<Record<string, string>>;
    description: string | Readonly<Record<string, string>>;
    renderUrl: string;
    slots: readonly AppSlot[];
    context?: readonly ContextSlice[];
    scopes?: readonly Scope[];
    tutorNote?: boolean;
    defaultLocale?: string;
}

name (string | Readonly<Record<string, string>>) — Nama aplikasi: satu rentetan, atau satu rentetan bagi setiap kod lokaliti.
description (string | Readonly<Record<string, string>>) — Satu ayat tentang aplikasi: satu rentetan, atau satu rentetan bagi setiap kod lokaliti.
renderUrl (string) — Alamat HTTPS tempat Lingara meminta kad aplikasi.
slots (readonly AppSlot[]) — Tempat kad aplikasi boleh muncul.
context? (readonly ContextSlice[]) — Bahagian konteks yang diterima oleh aplikasi. Lalai tiada.
scopes? (readonly Scope[]) — Kebenaran yang diminta oleh aplikasi daripada pelajar. Lalai tiada.
tutorNote? (boolean) — Sama ada aplikasi boleh meninggalkan nota untuk tutor. Lalai false.
defaultLocale? (string) — Lokaliti tempat nama atau penerangan rentetan biasa disimpan. Lalai "en".

`AppOptions`

Pilihan untuk lingara.app.

export interface AppOptions {
    client: NodeHandle;
    manifest: Manifest;
}

client (NodeHandle) — Langkah klien yang memiliki aplikasi ini: input.client.
manifest (Manifest) — Manifes aplikasi, yang dibina dengan lingara.manifest.

`ClientSpec`

Apa yang dibuat oleh langkah klien: klien API.

export interface ClientSpec {
    readonly kind: 'client';
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
}

kind ('client') — Sentiasa "client".
name (string) — Nama klien.
scopes (readonly Scope[]) — Kebenaran yang diminta oleh klien.
redirectUris? (readonly string[]) — URI ubah hala klien, apabila ia mempunyainya.

`SecretSpec`

Apa yang dibuat oleh langkah rahsia: rahsia baharu untuk kliennya.

export interface SecretSpec {
    readonly kind: 'secret';
    readonly client: NodeHandle;
}

kind ('secret') — Sentiasa "secret".
client (NodeHandle) — Langkah klien yang memiliki rahsia itu.

`WebhookSpec`

Apa yang dibuat oleh langkah webhook: titik akhir webhook.

export interface WebhookSpec {
    readonly kind: 'webhook';
    readonly client: NodeHandle;
    readonly url: string;
    readonly events: readonly string[];
}

kind ('webhook') — Sentiasa "webhook".
client (NodeHandle) — Langkah klien yang memiliki webhook itu.
url (string) — Alamat tempat acara dihantar.
events (readonly string[]) — Jenis acara yang dihantar.

`AppSpec`

Apa yang dibuat oleh langkah aplikasi: aplikasi yang memaparkan kad di dalam Lingara.

export interface AppSpec {
    readonly kind: 'app';
    readonly client: NodeHandle;
    readonly manifest: Manifest;
}

kind ('app') — Sentiasa "app".
client (NodeHandle) — Langkah klien yang memiliki aplikasi itu.
manifest (Manifest) — Manifes aplikasi.

`Manifest`

Manifes aplikasi dalam bentuk wayarnya, seperti yang disimpan oleh pelayan.

export interface Manifest {
    readonly manifest_version: 1;
    readonly default_locale: string;
    readonly name: Readonly<Record<string, string>>;
    readonly description: Readonly<Record<string, string>>;
    readonly render_url: string;
    readonly slots: readonly AppSlot[];
    readonly context: readonly ContextSlice[];
    readonly scopes: readonly Scope[];
    readonly tutor_note: boolean;
}

manifest_version (1) — Sentiasa 1.
default_locale (string) — Lokaliti yang dipaparkan apabila lokaliti pelajar sendiri tiada entri.
name (Readonly<Record<string, string>>) — Nama aplikasi, mengikut kod lokaliti.
description (Readonly<Record<string, string>>) — Satu ayat tentang aplikasi, mengikut kod lokaliti.
render_url (string) — Alamat HTTPS tempat Lingara meminta kad aplikasi.
slots (readonly AppSlot[]) — Tempat kad aplikasi boleh muncul.
context (readonly ContextSlice[]) — Bahagian konteks yang diterima oleh aplikasi.
scopes (readonly Scope[]) — Kebenaran yang diminta oleh aplikasi daripada pelajar.
tutor_note (boolean) — Sama ada aplikasi boleh meninggalkan nota untuk tutor.

`Spec`

Mana-mana spesifikasi yang dikembalikan oleh pembantu. Skrip mengembalikan tepat satu.

export type Spec = ClientSpec | SecretSpec | WebhookSpec | AppSpec;

`Upstream`

Output setiap langkah huluan langsung, mengikut pemegang.

export type Upstream = Readonly<Record<NodeHandle, Spec & {
    readonly handle: NodeHandle;
}>>;

`ClientInput`

Input langkah klien: medannya, iaitu pilihan lingara.client.

export interface ClientInput {
    readonly name: string;
    readonly scopes: readonly Scope[];
    readonly redirectUris?: readonly string[];
    readonly upstream: Upstream;
}

name (string) — Nama klien.
scopes (readonly Scope[]) — Kebenaran yang diminta oleh klien.
redirectUris? (readonly string[]) — URI ubah hala klien, apabila langkah itu mempunyainya.
upstream (Upstream) — Output setiap langkah huluan langsung.

`SecretInput`

Input langkah rahsia. client ialah satu-satunya langkah klien yang disambungkan kepada langkah ini.

export interface SecretInput {
    readonly client: NodeHandle;
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang disambungkan kepada langkah ini.
upstream (Upstream) — Output setiap langkah huluan langsung.

`WebhookInput`

Input langkah webhook: medannya, serta klien yang disambungkan.

export interface WebhookInput {
    readonly client: NodeHandle;
    readonly url: string;
    readonly events: readonly string[];
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang disambungkan kepada langkah ini.
url (string) — Alamat yang dinamakan oleh medan langkah.
events (readonly string[]) — Jenis acara yang dinamakan oleh medan langkah.
upstream (Upstream) — Output setiap langkah huluan langsung.

`AppInput`

Input langkah aplikasi: medan manifesnya, serta klien yang disambungkan.

export interface AppInput {
    readonly client: NodeHandle;
    readonly manifest: ManifestOptions;
    readonly upstream: Upstream;
}

client (NodeHandle) — Langkah klien yang disambungkan kepada langkah ini.
manifest (ManifestOptions) — Manifes yang diterangkan oleh medan langkah.
upstream (Upstream) — Output setiap langkah huluan langsung.

`InputFor`

Input yang diterima oleh skrip bagi jenis langkah yang diberikan.

export type InputFor<K extends Spec['kind']> = K extends 'client' ? ClientInput : K extends 'secret' ? SecretInput : K extends 'webhook' ? WebhookInput : AppInput;

`LingaraV1`

Pembantu yang dipanggil oleh skrip. Setiap satu mengembalikan spesifikasi beku, dan pilihan yang salah jenis melontar TypeError yang menamakannya.

export interface LingaraV1 {
    readonly version: 'v1';
    client(options: ClientOptions): ClientSpec;
    secret(client: NodeHandle): SecretSpec;
    webhook(options: WebhookOptions): WebhookSpec;
    app(options: AppOptions): AppSpec;
    manifest(options: ManifestOptions): Manifest;
}

version ('v1') — Sentiasa "v1".
client(options: ClientOptions): ClientSpec — Klien API.
secret(client: NodeHandle): SecretSpec — Rahsia baharu untuk langkah klien.
webhook(options: WebhookOptions): WebhookSpec — Titik akhir webhook pada langkah klien.
app(options: AppOptions): AppSpec — Aplikasi pada langkah klien.
manifest(options: ManifestOptions): Manifest — Manifes dalam bentuk wayarnya, dengan pilihan yang dibiarkan pilihan oleh v1 telah diisi.

return lingara.client({ name: input.name, scopes: input.scopes })

return lingara.secret(input.client)

return lingara.webhook({ client: input.client, url: input.url, events: input.events })

return lingara.app({ client: input.client, manifest: lingara.manifest(input.manifest) })

`NodeScript`

Skrip sesuatu langkah ialah badan fungsi ini: return lingara.webhook({ client: input.client, url: input.url, events: input.events }).

export type NodeScript<K extends Spec['kind']> = (lingara: LingaraV1, input: InputFor<K>) => Spec;

Lihat juga

Pengesahan