Lingara-kehittäjädokumentaatio

Tämä sivu on käännetty englannista. Jos ne eroavat toisistaan, englanninkielinen sivu on oikea. Lue englanninkielinen sivu

Yhteys koostuu vaiheista, ja missä tahansa vaiheessa voi olla skripti. Vaiheen skripti on funktion runko. Se saa kaksi arvoa: lingara, tämän sivun API, ja input, vaiheen omat kentät yhdessä sen asiakkaan ja ennen sitä liitettyjen vaiheiden kanssa. Arvon input tyyppi riippuu vaiheen lajista, joten webhook-vaiheen skripti lukee webhook-vaiheen kenttiä. Skripti palauttaa täsmälleen yhden objektin, jonka rakentaa jokin alla olevista apufunktioista.

Skripti ei koskaan näe salaisuutta. Kun vaihe tarvitsee asiakastaan, se saa kahvan, kuten input.client, ja apufunktio kirjaa tämän kahvan. Lingara täyttää todelliset arvot, kun otat yhteyden käyttöön.

Mitä skripti ei saa tehdä

Skripti suoritetaan omassa selaimessasi workerissa, jolla ei ole verkkoa eikä tallennustilaa. Sitä sitovat nämä rajat:

Se valmistuu 1 sekunnin kuluessa.
Sen palauttama merkkijono on enintään 2048 merkkiä pitkä.
Sen palauttamassa listassa on enintään 64 kohdetta.
Sen koko tulos on enintään 16 KiB.

Skripti, joka ylittää rajan, heittää virheen tai palauttaa jotain muuta kuin yhden apufunktion tuloksen, saa vaiheensa epäonnistumaan, ja “Tarkista” näyttää, mikä vaihe ja miksi.

Versiolupaus

Kaikki tällä sivulla on lingara.v1. Version v1 sisällä API vain kasvaa: uusi apufunktio, uusi valinnainen asetus tai uusi vaihelaji voi ilmestyä, mutta mitään, mitä voit käyttää tänään, ei poisteta, nimetä uudelleen tai kavenneta. Muutos, joka rikkoisi skriptin, on uusi versio tämän rinnalla, ja v1 pysyy ennallaan.

Määrittelyt

Jokainen alla oleva määrittely on generoitu samasta tiedostosta, jota vasten skriptieditori täydentää.

`NodeHandle`

Toisen vaiheen tunniste, kuten "n1". Riippuvainen vaihe nimeää asiakkaansa kahvalla.

export type NodeHandle = string;

`Scope`

Oikeus, joka API-asiakkaalla voi olla. Palvelin ratkaisee, mitä niistä tilisi saa käyttää.

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

`AppSlot`

Paikka Lingara-sovelluksessa, jossa sovelluksen kortti voi näkyä.

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

`ContextSlice`

Osa oppijan kontekstista, jota sovellus voi pyytää saada.

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

`ClientOptions`

Asetukset funktiolle lingara.client.

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

name (string) — Asiakkaan nimi sellaisena kuin Kehittäjätyökalut sen näyttää.
scopes (readonly Scope[]) — Oikeudet, joita asiakas pyytää.
redirectUris? (readonly string[]) — Minne valtuutuskoodikulku saa ohjata oppijan takaisin. Jätä pois palvelimelta palvelimelle -asiakkaalta.

`WebhookOptions`

Asetukset funktiolle lingara.webhook.

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

client (NodeHandle) — Asiakasvaihe, johon tämä webhook kuuluu: input.client.
url (string) — HTTPS-osoite, johon Lingara toimittaa tapahtumat.
events (readonly string[]) — Toimitettavat tapahtumatyypit, kuten "lesson_plan.ready".

`ManifestOptions`

Asetukset funktiolle lingara.manifest camelCase-muodossa; apufunktio kirjoittaa manifestin siirtomuodon.

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>>) — Sovelluksen nimi: yksi merkkijono tai yksi merkkijono kutakin kielikoodia kohden.
description (string | Readonly<Record<string, string>>) — Yksi virke sovelluksesta: yksi merkkijono tai yksi merkkijono kutakin kielikoodia kohden.
renderUrl (string) — HTTPS-osoite, jolta Lingara pyytää sovelluksen korttia.
slots (readonly AppSlot[]) — Missä sovelluksen kortti saa näkyä.
context? (readonly ContextSlice[]) — Kontekstin osat, jotka sovellus saa. Oletuksena ei mitään.
scopes? (readonly Scope[]) — Oikeudet, joita sovellus pyytää oppijalta. Oletuksena ei mitään.
tutorNote? (boolean) — Saako sovellus jättää muistiinpanon tutorille. Oletuksena false.
defaultLocale? (string) — Kieli, jonka alle pelkkänä merkkijonona annettu nimi tai kuvaus tallennetaan. Oletuksena "en".

`AppOptions`

Asetukset funktiolle lingara.app.

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

client (NodeHandle) — Asiakasvaihe, johon tämä sovellus kuuluu: input.client.
manifest (Manifest) — Sovelluksen manifesti, joka on rakennettu funktiolla lingara.manifest.

`ClientSpec`

Mitä asiakasvaihe luo: API-asiakkaan.

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

kind ('client') — Aina "client".
name (string) — Asiakkaan nimi.
scopes (readonly Scope[]) — Oikeudet, joita asiakas pyytää.
redirectUris? (readonly string[]) — Asiakkaan uudelleenohjaus-URI:t, jos niitä on.

`SecretSpec`

Mitä salaisuusvaihe luo: uuden salaisuuden asiakkaalleen.

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

kind ('secret') — Aina "secret".
client (NodeHandle) — Asiakasvaihe, johon salaisuus kuuluu.

`WebhookSpec`

Mitä webhook-vaihe luo: webhook-päätepisteen.

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

kind ('webhook') — Aina "webhook".
client (NodeHandle) — Asiakasvaihe, johon webhook kuuluu.
url (string) — Osoite, johon tapahtumat toimitetaan.
events (readonly string[]) — Toimitettavat tapahtumatyypit.

`AppSpec`

Mitä sovellusvaihe luo: sovelluksen, joka näyttää kortin Lingarassa.

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

kind ('app') — Aina "app".
client (NodeHandle) — Asiakasvaihe, johon sovellus kuuluu.
manifest (Manifest) — Sovelluksen manifesti.

`Manifest`

Sovellusmanifesti siirtomuodossaan, sellaisena kuin palvelin sen tallentaa.

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) — Aina 1.
default_locale (string) — Kieli, joka näytetään, kun oppijan omalle kielelle ei ole merkintää.
name (Readonly<Record<string, string>>) — Sovelluksen nimi kielikoodeittain.
description (Readonly<Record<string, string>>) — Yksi virke sovelluksesta kielikoodeittain.
render_url (string) — HTTPS-osoite, jolta Lingara pyytää sovelluksen korttia.
slots (readonly AppSlot[]) — Missä sovelluksen kortti saa näkyä.
context (readonly ContextSlice[]) — Kontekstin osat, jotka sovellus saa.
scopes (readonly Scope[]) — Oikeudet, joita sovellus pyytää oppijalta.
tutor_note (boolean) — Saako sovellus jättää muistiinpanon tutorille.

`Spec`

Mikä tahansa apufunktion palauttama spec. Skripti palauttaa niistä täsmälleen yhden.

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

`Upstream`

Jokaisen suoraan edeltävän vaiheen tuloste kahvan mukaan.

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

`ClientInput`

Asiakasvaiheen syöte: sen kentät, jotka ovat funktion lingara.client asetukset.

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

name (string) — Asiakkaan nimi.
scopes (readonly Scope[]) — Oikeudet, joita asiakas pyytää.
redirectUris? (readonly string[]) — Asiakkaan uudelleenohjaus-URI:t, jos vaiheella on niitä.
upstream (Upstream) — Jokaisen suoraan edeltävän vaiheen tuloste.

`SecretInput`

Salaisuusvaiheen syöte. client on se yksi asiakasvaihe, joka on liitetty tähän vaiheeseen.

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

client (NodeHandle) — Tähän vaiheeseen liitetty asiakasvaihe.
upstream (Upstream) — Jokaisen suoraan edeltävän vaiheen tuloste.

`WebhookInput`

Webhook-vaiheen syöte: sen kentät sekä liitetty asiakas.

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

client (NodeHandle) — Tähän vaiheeseen liitetty asiakasvaihe.
url (string) — Osoite, jonka vaiheen kentät nimeävät.
events (readonly string[]) — Tapahtumatyypit, jotka vaiheen kentät nimeävät.
upstream (Upstream) — Jokaisen suoraan edeltävän vaiheen tuloste.

`AppInput`

Sovellusvaiheen syöte: sen manifestikentät sekä liitetty asiakas.

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

client (NodeHandle) — Tähän vaiheeseen liitetty asiakasvaihe.
manifest (ManifestOptions) — Manifesti, jonka vaiheen kentät kuvaavat.
upstream (Upstream) — Jokaisen suoraan edeltävän vaiheen tuloste.

`InputFor`

Syöte, jonka annetun vaihelajin skripti saa.

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

`LingaraV1`

Apufunktiot, joita skripti kutsuu. Jokainen palauttaa jäädytetyn specin, ja väärän tyyppinen asetus heittää sen nimeävän TypeError-virheen.

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') — Aina "v1".
client(options: ClientOptions): ClientSpec — API-asiakas.
secret(client: NodeHandle): SecretSpec — Uusi salaisuus asiakasvaiheelle.
webhook(options: WebhookOptions): WebhookSpec — Webhook-päätepiste asiakasvaiheessa.
app(options: AppOptions): AppSpec — Sovellus asiakasvaiheessa.
manifest(options: ManifestOptions): Manifest — Manifesti siirtomuodossaan, ja asetukset, jotka v1 jättää valinnaisiksi, on täytetty.

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`

Vaiheen skripti on tämän funktion runko: 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;

Katso myös

Todennus