Lingara 開発者ドキュメント

このページは英語から翻訳されています。内容に相違がある場合は、英語のページが正しい内容です。 英語のページを読む

連携は手順で構成され、どの手順にもスクリプトを持たせることができます。手順のスクリプトは関数の本体です。受け取る値は 2 つで、このページの API である lingara と、手順自身の入力項目にそのクライアントとその手順より前に結合された手順を合わせた input です。input の型は手順の種類によって決まるため、Webhook 手順のスクリプトは Webhook 手順の入力項目を読み取ります。スクリプトは、下記のヘルパーのいずれかで作成したオブジェクトをちょうど 1 つ返します。

スクリプトがシークレットを目にすることはありません。手順がクライアントを必要とする場合は input.client のようなハンドルを受け取り、ヘルパーはそのハンドルを記録します。実際の値は、連携を適用するときに Lingara が埋めます。

スクリプトがしてはいけないこと

スクリプトはあなた自身のブラウザーで、ネットワークもストレージもないワーカーの中で実行されます。次の制限が課されます。

• 1 秒以内に終了すること。
• 返す文字列は最大 2048 文字であること。
• 返すリストの項目は最大 64 個であること。
• 結果全体は最大 16 KiB であること。

制限に違反したり、例外をスローしたり、ヘルパーの結果以外のものを返したりしたスクリプトはその手順を失敗させ、「確認する」でどの手順がなぜ失敗したかが表示されます。

バージョンの約束

このページのすべては lingara.v1 です。v1 の中では、API は拡張されるだけです。新しいヘルパー、新しい任意のオプション、新しい手順の種類が加わることはあっても、現在使えるものが削除されたり、名前が変わったり、範囲が狭められたりすることはありません。スクリプトを壊すような変更は、このバージョンと並ぶ新しいバージョンとなり、v1 はそのまま残ります。

宣言

以下の各宣言は、スクリプトエディターの補完が参照するのと同じファイルから生成されています。

NodeHandle

別の手順の ID です（例："n1"）。依存する手順は、自分のクライアントをハンドルで指定します。

export type NodeHandle = string;

Scope

API クライアントが持てる権限です。あなたのアカウントがどれを使えるかはサーバーが判断します。

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

AppSlot

Lingara アプリの中で、アプリのカードが表示されうる場所です。

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

ContextSlice

アプリが受け取りを求めることができる、学習者のコンテキストの一部です。

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

ClientOptions

lingara.client のオプションです。

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

• name (string) — 開発者ツールに表示される、クライアントの名前。
• scopes (readonly Scope[]) — クライアントが求める権限。
• redirectUris? (readonly string[]) — 認可コードフローで学習者を送り返せる先。サーバー間のクライアントでは省略します。

WebhookOptions

lingara.webhook のオプションです。

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

• client (NodeHandle) — この Webhook が属するクライアント手順：input.client。
• url (string) — Lingara がイベントを配信する HTTPS アドレス。
• events (readonly string[]) — 配信するイベントの種類（例："lesson_plan.ready"）。

ManifestOptions

lingara.manifest のオプションで、camelCase で書きます。ヘルパーがマニフェストのワイヤー形式を書き出します。

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>>) — アプリの名前：1 つの文字列、またはロケールコードごとに 1 つの文字列。
• description (string | Readonly<Record<string, string>>) — アプリについての 1 文：1 つの文字列、またはロケールコードごとに 1 つの文字列。
• renderUrl (string) — Lingara がアプリのカードを要求する HTTPS アドレス。
• slots (readonly AppSlot[]) — アプリのカードを表示できる場所。
• context? (readonly ContextSlice[]) — アプリが受け取るコンテキストの一部。既定ではなし。
• scopes? (readonly Scope[]) — アプリが学習者に求める権限。既定ではなし。
• tutorNote? (boolean) — アプリがチューターにメモを残せるかどうか。既定は false。
• defaultLocale? (string) — 単純な文字列で書いた名前や説明が保存されるロケール。既定は "en"。

AppOptions

lingara.app のオプションです。

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

• client (NodeHandle) — このアプリが属するクライアント手順：input.client。
• manifest (Manifest) — lingara.manifest で作成した、アプリのマニフェスト。

ClientSpec

クライアント手順が作るもの：API クライアント。

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

• kind ('client') — 常に "client"。
• name (string) — クライアントの名前。
• scopes (readonly Scope[]) — クライアントが求める権限。
• redirectUris? (readonly string[]) — クライアントのリダイレクト URI（ある場合）。

SecretSpec

シークレット手順が作るもの：そのクライアントの新しいシークレット。

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

• kind ('secret') — 常に "secret"。
• client (NodeHandle) — シークレットが属するクライアント手順。

WebhookSpec

Webhook 手順が作るもの：Webhook エンドポイント。

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

• kind ('webhook') — 常に "webhook"。
• client (NodeHandle) — Webhook が属するクライアント手順。
• url (string) — イベントの配信先アドレス。
• events (readonly string[]) — 配信されるイベントの種類。

AppSpec

アプリ手順が作るもの：Lingara 内にカードを描画するアプリ。

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

• kind ('app') — 常に "app"。
• client (NodeHandle) — アプリが属するクライアント手順。
• manifest (Manifest) — アプリのマニフェスト。

Manifest

サーバーが保存するとおりの、ワイヤー形式のアプリマニフェストです。

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) — 常に 1。
• default_locale (string) — 学習者自身のロケールに項目がないときに表示されるロケール。
• name (Readonly<Record<string, string>>) — ロケールコードごとのアプリの名前。
• description (Readonly<Record<string, string>>) — ロケールコードごとの、アプリについての 1 文。
• render_url (string) — Lingara がアプリのカードを要求する HTTPS アドレス。
• slots (readonly AppSlot[]) — アプリのカードを表示できる場所。
• context (readonly ContextSlice[]) — アプリが受け取るコンテキストの一部。
• scopes (readonly Scope[]) — アプリが学習者に求める権限。
• tutor_note (boolean) — アプリがチューターにメモを残せるかどうか。

Spec

ヘルパーが返すあらゆる spec です。スクリプトはちょうど 1 つを返します。

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

Upstream

直接の上流にある各手順の出力を、ハンドルごとにまとめたものです。

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

ClientInput

クライアント手順の入力：その入力項目で、lingara.client のオプションと同じです。

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

• name (string) — クライアントの名前。
• scopes (readonly Scope[]) — クライアントが求める権限。
• redirectUris? (readonly string[]) — クライアントのリダイレクト URI（手順にある場合）。
• upstream (Upstream) — 直接の上流にある各手順の出力。

SecretInput

シークレット手順の入力です。client は、この手順に結合された唯一のクライアント手順です。

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

• client (NodeHandle) — この手順に結合されたクライアント手順。
• upstream (Upstream) — 直接の上流にある各手順の出力。

WebhookInput

Webhook 手順の入力：その入力項目と、結合されたクライアント。

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

• client (NodeHandle) — この手順に結合されたクライアント手順。
• url (string) — 手順の入力項目が指定するアドレス。
• events (readonly string[]) — 手順の入力項目が指定するイベントの種類。
• upstream (Upstream) — 直接の上流にある各手順の出力。

AppInput

アプリ手順の入力：マニフェストの入力項目と、結合されたクライアント。

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

• client (NodeHandle) — この手順に結合されたクライアント手順。
• manifest (ManifestOptions) — 手順の入力項目が記述するマニフェスト。
• upstream (Upstream) — 直接の上流にある各手順の出力。

InputFor

指定した種類の手順のスクリプトが受け取る入力です。

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

LingaraV1

スクリプトが呼び出すヘルパーです。それぞれ凍結された spec を返し、型の誤ったオプションに対しては、そのオプションを名指しする TypeError をスローします。

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') — 常に "v1"。
• client(options: ClientOptions): ClientSpec — API クライアント。
• secret(client: NodeHandle): SecretSpec — クライアント手順の新しいシークレット。
• webhook(options: WebhookOptions): WebhookSpec — クライアント手順上の Webhook エンドポイント。
• app(options: AppOptions): AppSpec — クライアント手順上のアプリ。
• manifest(options: ManifestOptions): Manifest — ワイヤー形式のマニフェスト。v1 が任意としているオプションは埋められています。

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

手順のスクリプトは、この関数の本体です：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;