Tài liệu dành cho nhà phát triển Lingara

Trang này được dịch từ tiếng Anh. Nếu hai bản khác nhau, trang tiếng Anh là bản đúng. Đọc trang tiếng Anh

Một kết nối được tạo thành từ các bước, và bước nào cũng có thể mang một tập lệnh. Tập lệnh của một bước là phần thân của một hàm. Nó nhận hai giá trị: lingara, API trên trang này, và input, các trường của chính bước đó cùng với ứng dụng khách của nó và các bước được nối trước nó. Kiểu của input phụ thuộc vào loại bước, nên tập lệnh của một bước webhook đọc các trường của bước webhook. Tập lệnh trả về đúng một đối tượng, được tạo bởi một trong các hàm trợ giúp bên dưới.

Tập lệnh không bao giờ nhìn thấy khóa bí mật. Khi một bước cần ứng dụng khách của nó, bước đó nhận một handle, chẳng hạn input.client, và hàm trợ giúp ghi lại handle đó. Lingara điền các giá trị thật khi bạn áp dụng kết nối.

Những điều tập lệnh không được làm

Tập lệnh chạy trong trình duyệt của chính bạn, trong một worker không có mạng và không có bộ nhớ lưu trữ. Nó phải tuân theo các giới hạn sau:

Nó kết thúc trong vòng 1 giây.
Một chuỗi nó trả về dài tối đa 2048 ký tự.
Một danh sách nó trả về có tối đa 64 mục.
Toàn bộ kết quả của nó tối đa 16 KiB.

Tập lệnh vi phạm một giới hạn, ném ra ngoại lệ, hoặc trả về thứ gì khác ngoài kết quả của một hàm trợ giúp sẽ làm bước của nó thất bại, và “Kiểm tra ngay” cho biết bước nào và vì sao.

Cam kết về phiên bản

Mọi thứ trên trang này là lingara.v1. Trong v1, API chỉ mở rộng thêm: một hàm trợ giúp mới, một tùy chọn không bắt buộc mới hoặc một loại bước mới có thể xuất hiện, nhưng không gì bạn có thể dùng hôm nay bị xóa, đổi tên hay thu hẹp. Một thay đổi có thể làm hỏng tập lệnh sẽ là một phiên bản mới bên cạnh phiên bản này, và v1 vẫn giữ nguyên.

Các khai báo

Mỗi khai báo bên dưới được tạo ra từ chính tệp mà trình soạn thảo tập lệnh dùng để tự động hoàn thành.

`NodeHandle`

Id của một bước khác, chẳng hạn "n1". Một bước phụ thuộc gọi tên ứng dụng khách của nó bằng handle.

export type NodeHandle = string;

`Scope`

Một quyền mà ứng dụng khách API có thể nắm giữ. Máy chủ quyết định tài khoản của bạn được dùng những quyền nào.

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

`AppSlot`

Một vị trí trong ứng dụng Lingara nơi thẻ của một ứng dụng có thể xuất hiện.

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

`ContextSlice`

Một phần ngữ cảnh của người học mà ứng dụng có thể yêu cầu nhận.

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

`ClientOptions`

Các tùy chọn cho lingara.client.

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

name (string) — Tên của ứng dụng khách, như Công cụ dành cho nhà phát triển hiển thị.
scopes (readonly Scope[]) — Các quyền mà ứng dụng khách yêu cầu.
redirectUris? (readonly string[]) — Nơi luồng mã ủy quyền có thể đưa người học quay về. Bỏ qua đối với ứng dụng khách giữa máy chủ với máy chủ.

`WebhookOptions`

Các tùy chọn cho lingara.webhook.

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

client (NodeHandle) — Bước ứng dụng khách mà webhook này thuộc về: input.client.
url (string) — Địa chỉ HTTPS mà Lingara gửi sự kiện đến.
events (readonly string[]) — Các loại sự kiện cần gửi, chẳng hạn "lesson_plan.ready".

`ManifestOptions`

Các tùy chọn cho lingara.manifest, viết theo camelCase; hàm trợ giúp viết ra dạng truyền tải của tệp kê khai.

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>>) — Tên của ứng dụng: một chuỗi, hoặc một chuỗi cho mỗi mã ngôn ngữ.
description (string | Readonly<Record<string, string>>) — Một câu về ứng dụng: một chuỗi, hoặc một chuỗi cho mỗi mã ngôn ngữ.
renderUrl (string) — Địa chỉ HTTPS mà Lingara yêu cầu thẻ của ứng dụng.
slots (readonly AppSlot[]) — Nơi thẻ của ứng dụng có thể xuất hiện.
context? (readonly ContextSlice[]) — Các phần ngữ cảnh mà ứng dụng nhận. Mặc định là không có.
scopes? (readonly Scope[]) — Các quyền mà ứng dụng xin người học. Mặc định là không có.
tutorNote? (boolean) — Ứng dụng có được để lại ghi chú cho gia sư hay không. Mặc định là false.
defaultLocale? (string) — Ngôn ngữ mà tên hoặc mô tả dạng chuỗi đơn được lưu dưới đó. Mặc định là "en".

`AppOptions`

Các tùy chọn cho lingara.app.

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

client (NodeHandle) — Bước ứng dụng khách mà ứng dụng này thuộc về: input.client.
manifest (Manifest) — Tệp kê khai của ứng dụng, được tạo bằng lingara.manifest.

`ClientSpec`

Những gì một bước ứng dụng khách tạo ra: một ứng dụng khách API.

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

kind ('client') — Luôn là "client".
name (string) — Tên của ứng dụng khách.
scopes (readonly Scope[]) — Các quyền mà ứng dụng khách yêu cầu.
redirectUris? (readonly string[]) — Các URI chuyển hướng của ứng dụng khách, nếu có.

`SecretSpec`

Những gì một bước khóa bí mật tạo ra: một khóa bí mật mới cho ứng dụng khách của nó.

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

kind ('secret') — Luôn là "secret".
client (NodeHandle) — Bước ứng dụng khách mà khóa bí mật thuộc về.

`WebhookSpec`

Những gì một bước webhook tạo ra: một điểm cuối webhook.

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

kind ('webhook') — Luôn là "webhook".
client (NodeHandle) — Bước ứng dụng khách mà webhook thuộc về.
url (string) — Địa chỉ mà sự kiện được gửi đến.
events (readonly string[]) — Các loại sự kiện được gửi.

`AppSpec`

Những gì một bước ứng dụng tạo ra: một ứng dụng hiển thị thẻ bên trong Lingara.

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

kind ('app') — Luôn là "app".
client (NodeHandle) — Bước ứng dụng khách mà ứng dụng thuộc về.
manifest (Manifest) — Tệp kê khai của ứng dụng.

`Manifest`

Một tệp kê khai ứng dụng ở dạng truyền tải, đúng như máy chủ lưu trữ.

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) — Luôn là 1.
default_locale (string) — Ngôn ngữ được hiển thị khi ngôn ngữ của người học không có mục tương ứng.
name (Readonly<Record<string, string>>) — Tên của ứng dụng, theo từng mã ngôn ngữ.
description (Readonly<Record<string, string>>) — Một câu về ứng dụng, theo từng mã ngôn ngữ.
render_url (string) — Địa chỉ HTTPS mà Lingara yêu cầu thẻ của ứng dụng.
slots (readonly AppSlot[]) — Nơi thẻ của ứng dụng có thể xuất hiện.
context (readonly ContextSlice[]) — Các phần ngữ cảnh mà ứng dụng nhận.
scopes (readonly Scope[]) — Các quyền mà ứng dụng xin người học.
tutor_note (boolean) — Ứng dụng có được để lại ghi chú cho gia sư hay không.

`Spec`

Bất kỳ spec nào mà một hàm trợ giúp trả về. Một tập lệnh trả về đúng một spec.

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

`Upstream`

Đầu ra của từng bước thượng nguồn trực tiếp, theo handle.

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

`ClientInput`

Đầu vào của một bước ứng dụng khách: các trường của nó, chính là các tùy chọn của lingara.client.

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

name (string) — Tên của ứng dụng khách.
scopes (readonly Scope[]) — Các quyền mà ứng dụng khách yêu cầu.
redirectUris? (readonly string[]) — Các URI chuyển hướng của ứng dụng khách, nếu bước có.
upstream (Upstream) — Đầu ra của từng bước thượng nguồn trực tiếp.

`SecretInput`

Đầu vào của một bước khóa bí mật. client là bước ứng dụng khách duy nhất được nối với bước này.

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

client (NodeHandle) — Bước ứng dụng khách được nối với bước này.
upstream (Upstream) — Đầu ra của từng bước thượng nguồn trực tiếp.

`WebhookInput`

Đầu vào của một bước webhook: các trường của nó, cộng với ứng dụng khách được nối.

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

client (NodeHandle) — Bước ứng dụng khách được nối với bước này.
url (string) — Địa chỉ mà các trường của bước nêu ra.
events (readonly string[]) — Các loại sự kiện mà các trường của bước nêu ra.
upstream (Upstream) — Đầu ra của từng bước thượng nguồn trực tiếp.

`AppInput`

Đầu vào của một bước ứng dụng: các trường tệp kê khai của nó, cộng với ứng dụng khách được nối.

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

client (NodeHandle) — Bước ứng dụng khách được nối với bước này.
manifest (ManifestOptions) — Tệp kê khai mà các trường của bước mô tả.
upstream (Upstream) — Đầu ra của từng bước thượng nguồn trực tiếp.

`InputFor`

Đầu vào mà tập lệnh của loại bước đã cho nhận được.

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

`LingaraV1`

Các hàm trợ giúp mà tập lệnh gọi. Mỗi hàm trả về một spec đã đóng băng, và một tùy chọn sai kiểu sẽ ném ra TypeError nêu tên tùy chọn đó.

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') — Luôn là "v1".
client(options: ClientOptions): ClientSpec — Một ứng dụng khách API.
secret(client: NodeHandle): SecretSpec — Một khóa bí mật mới cho một bước ứng dụng khách.
webhook(options: WebhookOptions): WebhookSpec — Một điểm cuối webhook trên một bước ứng dụng khách.
app(options: AppOptions): AppSpec — Một ứng dụng trên một bước ứng dụng khách.
manifest(options: ManifestOptions): Manifest — Một tệp kê khai ở dạng truyền tải, với các tùy chọn mà v1 để không bắt buộc đã được điền sẵn.

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`

Tập lệnh của một bước là phần thân của hàm này: 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;

Xem thêm

Xác thực