Τεκμηρίωση για προγραμματιστές του Lingara

Αυτή η σελίδα έχει μεταφραστεί από τα αγγλικά. Αν οι δύο διαφέρουν, η αγγλική σελίδα είναι η σωστή. Διαβάστε την αγγλική σελίδα

Μια σύνδεση αποτελείται από βήματα, και κάθε βήμα μπορεί να έχει ένα σενάριο. Το σενάριο ενός βήματος είναι το σώμα μιας συνάρτησης. Λαμβάνει δύο τιμές: το lingara, το API αυτής της σελίδας, και το input, τα πεδία του ίδιου του βήματος μαζί με τον πελάτη του και τα βήματα που έχουν συνδεθεί πριν από αυτό. Ο τύπος του input εξαρτάται από το είδος του βήματος, οπότε το σενάριο ενός βήματος webhook διαβάζει τα πεδία ενός βήματος webhook. Το σενάριο επιστρέφει ακριβώς ένα αντικείμενο, δημιουργημένο με μία από τις παρακάτω βοηθητικές συναρτήσεις.

Ένα σενάριο δεν βλέπει ποτέ ένα μυστικό. Όπου ένα βήμα χρειάζεται τον πελάτη του, λαμβάνει ένα αναγνωριστικό, όπως το input.client, και η βοηθητική συνάρτηση καταγράφει αυτό το αναγνωριστικό. Το Lingara συμπληρώνει τις πραγματικές τιμές όταν εφαρμόζετε τη σύνδεση.

Τι δεν πρέπει να κάνει ένα σενάριο

Ένα σενάριο εκτελείται στο δικό σας πρόγραμμα περιήγησης, σε έναν worker χωρίς δίκτυο και χωρίς αποθήκευση. Υπόκειται στα εξής όρια:

Ολοκληρώνεται μέσα σε 1 δευτερόλεπτο.
Μια συμβολοσειρά που επιστρέφει έχει μήκος το πολύ 2048 χαρακτήρες.
Μια λίστα που επιστρέφει έχει το πολύ 64 στοιχεία.
Ολόκληρο το αποτέλεσμά του είναι το πολύ 16 KiB.

Ένα σενάριο που παραβιάζει ένα όριο, προκαλεί εξαίρεση ή επιστρέφει κάτι άλλο από το αποτέλεσμα μίας βοηθητικής συνάρτησης κάνει το βήμα του να αποτύχει, και ο «Έλεγχος» δείχνει ποιο βήμα και γιατί.

Η δέσμευση για την έκδοση

Όλα σε αυτή τη σελίδα ανήκουν στο lingara.v1. Μέσα στο v1 το API μόνο μεγαλώνει: μπορεί να εμφανιστεί μια νέα βοηθητική συνάρτηση, μια νέα προαιρετική επιλογή ή ένα νέο είδος βήματος, αλλά τίποτα από όσα μπορείτε να χρησιμοποιήσετε σήμερα δεν αφαιρείται, δεν μετονομάζεται και δεν περιορίζεται. Μια αλλαγή που θα χαλούσε ένα σενάριο είναι μια νέα έκδοση δίπλα σε αυτήν, και το v1 μένει όπως είναι.

Οι δηλώσεις

Κάθε δήλωση παρακάτω παράγεται από το ίδιο αρχείο βάσει του οποίου κάνει τις συμπληρώσεις του ο επεξεργαστής σεναρίων.

`NodeHandle`

Το αναγνωριστικό ενός άλλου βήματος, όπως το "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) — Η διεύθυνση HTTPS στην οποία το Lingara παραδίδει συμβάντα.
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>>) — Το όνομα της εφαρμογής: μία συμβολοσειρά ή μία συμβολοσειρά ανά κωδικό τοπικών ρυθμίσεων.
description (string | Readonly<Record<string, string>>) — Μία πρόταση για την εφαρμογή: μία συμβολοσειρά ή μία συμβολοσειρά ανά κωδικό τοπικών ρυθμίσεων.
renderUrl (string) — Η διεύθυνση HTTPS από την οποία το Lingara ζητά την κάρτα της εφαρμογής.
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>>) — Μία πρόταση για την εφαρμογή, ανά κωδικό τοπικών ρυθμίσεων.
render_url (string) — Η διεύθυνση HTTPS από την οποία το Lingara ζητά την κάρτα της εφαρμογής.
slots (readonly AppSlot[]) — Πού μπορεί να εμφανιστεί η κάρτα της εφαρμογής.
context (readonly ContextSlice[]) — Τα τμήματα πλαισίου που λαμβάνει η εφαρμογή.
scopes (readonly Scope[]) — Οι άδειες που ζητά η εφαρμογή από τον μαθητή.
tutor_note (boolean) — Αν η εφαρμογή μπορεί να αφήσει μια σημείωση για τον δάσκαλο.

`Spec`

Οποιαδήποτε προδιαγραφή επιστρέφει μια βοηθητική συνάρτηση. Ένα σενάριο επιστρέφει ακριβώς μία.

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`

Οι βοηθητικές συναρτήσεις που καλεί ένα σενάριο. Η καθεμία επιστρέφει μια παγωμένη προδιαγραφή, και μια επιλογή λάθος τύπου προκαλεί ένα 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;

Δείτε επίσης

Έλεγχος ταυτότητας