Freigeben über

Poller class

  • Referenz
Paket:
@azure/core-lro

Eine Klasse, die die Definition eines Programms darstellt, das aufeinanderfolgende Anforderungen abruft, bis es einen Abschlussstatus erreicht. Ein Poller kann manuell ausgeführt werden, indem Anforderung nach Anforderung abgerufen wird, indem die poll() Methode wiederholt aufgerufen wird, bis ihr Vorgang abgeschlossen ist. Es bietet auch eine Möglichkeit, zu warten, bis der Vorgang abgeschlossen ist, indem Sie aufrufen pollUntilDone() und warten, bis der Vorgang abgeschlossen ist. Poller können auch den Abbruch des laufenden Prozesses anfordern, für den der zugrunde liegende vorgang mit langer Ausführungsdauer bereitgestellt wird.

const poller = new MyPoller();

// Polling just once:
await poller.poll();

// We can try to cancel the request here, by calling:
//
//     await poller.cancelOperation();
//

// Getting the final result:
const result = await poller.pollUntilDone();

Der Poller wird durch zwei Typen definiert, einen Typ, der den Zustand des Pollers darstellt, der einen grundlegenden Satz von Eigenschaften von PollOperationState<TResult>enthalten muss, und einen durch definierten TResultRückgabetyp, der alles sein kann.

Die Poller-Klasse implementiert die PollerLike Schnittstelle, sodass Pollerimplementierungen nicht direkt die Poller-Klasse exportieren müssen, sondern nur den bereits instanziierten Poller mit dem PollerLike-Typ exportieren.

class Client {
  public async makePoller: PollerLike<MyOperationState, MyResult> {
    const poller = new MyPoller({});
    // It might be preferred to return the poller after the first request is made,
    // so that some information can be obtained right away.
    await poller.poll();
    return poller;
  }
}

const poller: PollerLike<MyOperationState, MyResult> = myClient.makePoller();

Ein Poller kann über seinen Konstruktor erstellt und dann abgefragt werden, bis er abgeschlossen ist. Der Zustand des Pollers kann jederzeit ohne Verzögerung über die getOperationState-Methode abgerufen werden. Die Zwischenformen des Ergebnistyps können jederzeit ohne Verzögerung angefordert werden. Sobald der zugrunde liegende Vorgang als abgeschlossen markiert wurde, wird der Poller beendet, und der endgültige Wert wird zurückgegeben.

const poller = myClient.makePoller();
const state: MyOperationState = poller.getOperationState();

// The intermediate result can be obtained at any time.
const result: MyResult | undefined = poller.getResult();

// The final result can only be obtained after the poller finishes.
const result: MyResult = await poller.pollUntilDone();

Konstruktoren

Poller(PollOperation<TState, TResult>)

Ein Poller muss initialisiert werden, indem mindestens die grundlegenden Eigenschaften von PollOperation<TState, TResult>übergeben werden. Beim Schreiben einer Implementierung eines Pollers muss sich diese Implementierung mit der Initialisierung eines beliebigen benutzerdefinierten Zustands befassen, der über die grundlegende Definition des Pollers hinausgeht. Der grundlegende Poller geht davon aus, dass der Vorgang des Pollers bereits definiert wurde, zumindest seine grundlegenden Eigenschaften. Der folgende Code zeigt, wie Sie sich der Definition des Konstruktors eines neuen benutzerdefinierten Pollers nähern.

export class MyPoller extends Poller<MyOperationState, string> {
  constructor({
    // Anything you might need outside of the basics
  }) {
    let state: MyOperationState = {
      privateProperty: private,
      publicProperty: public,
    };

    const operation = {
      state,
      update,
      cancel,
      toString
    }

    // Sending the operation to the parent's constructor.
    super(operation);

    // You can assign more local properties here.
  }
}

Innerhalb dieses Konstruktors wird eine neue Zusage erstellt. Dies wird verwendet, um dem Benutzer mitzuteilen, wann der Abrufvorgang abgeschlossen ist (siehe pollUntilDone()). Die Resolve- und Reject-Methoden der Zusage werden auch intern verwendet, um zu steuern, wann alle Personen, die auf den Abschluss des Abrufs warten, aufgelöst oder abgelehnt werden sollen.

Im Konstruktor einer benutzerdefinierten Implementierung eines Pollers sollte jede serialisierte Version des Vorgangs eines vorherigen Abfragevorgangs in den Vorgang deserialisiert werden, der an den Basiskonstruktor gesendet wird. Beispiel:

export class MyPoller extends Poller<MyOperationState, string> {
  constructor(
    baseOperation: string | undefined
  ) {
    let state: MyOperationState = {};
    if (baseOperation) {
      state = {
        ...JSON.parse(baseOperation).state,
        ...state
      };
    }
    const operation = {
      state,
      // ...
    }
    super(operation);
  }
}

Methoden

cancelOperation({ abortSignal?: AbortSignalLike })

Versucht, den zugrunde liegenden Vorgang abzubrechen. Es empfängt nur optional ein Objekt mit einer abortSignal-Eigenschaft von @azure/abort-controller AbortSignalLike.

Wenn es erneut aufgerufen wird, bevor er abgeschlossen ist, wird ein Fehler ausgelöst.
getOperationState()

Gibt den Status des Vorgangs zurück. Obwohl TState innerhalb einer beliebigen Erweiterung der Poller-Klasse derselbe Typ ist, können Implementierungen der Poller-Klasse anpassen, was für die Öffentlichkeit freigegeben wird, indem sie eine eigene Version der getOperationState Methode schreiben und zwei Typen definieren, einen, der den internen Zustand des Pollers darstellt, und einen öffentlichen Typ, der eine sichere Teilmenge der Eigenschaften des internen Zustands darstellt. Ihre Definition von getOperationState kann dann ihren öffentlichen Typ zurückgeben.

Beispiel:

// Let's say we have our poller's operation state defined as:
interface MyOperationState extends PollOperationState<ResultType> {
  privateProperty?: string;
  publicProperty?: string;
}

// To allow us to have a true separation of public and private state, we have to define another interface:
interface PublicState extends PollOperationState<ResultType> {
  publicProperty?: string;
}

// Then, we define our Poller as follows:
export class MyPoller extends Poller<MyOperationState, ResultType> {
  // ... More content is needed here ...

  public getOperationState(): PublicState {
    const state: PublicState = this.operation.state;
    return {
      // Properties from PollOperationState<TResult>
      isStarted: state.isStarted,
      isCompleted: state.isCompleted,
      isCancelled: state.isCancelled,
      error: state.error,
      result: state.result,

      // The only other property needed by PublicState.
      publicProperty: state.publicProperty
    }
  }
}

Sie können dies in den Tests dieses Repositorys sehen, wechseln Sie zur Datei:../test/utils/testPoller.ts und suchen Sie nach der getOperationState-Implementierung.
getResult()

Gibt den Ergebniswert des Vorgangs zurück, unabhängig vom Zustand des Pollers. Je nach Implementierung kann der endgültige TResult-Wert nicht definiert oder unvollständig zurückgegeben werden.
isDone()

Gibt true zurück, wenn der Poller die Abfrage abgeschlossen hat.
isStopped()

Gibt true zurück, wenn der Poller beendet wurde.
onProgress((state: TState) => void)

Ruft den bereitgestellten Rückruf auf, nachdem jede Abfrage abgeschlossen ist, und sendet den aktuellen Zustand des Abfragevorgangs. Es gibt eine Methode zurück, die verwendet werden kann, um den Empfang von Updates für die angegebene Rückruffunktion zu beenden.
poll({ abortSignal?: AbortSignalLike })

Gibt eine Zusage zurück, die aufgelöst wird, sobald eine einzelne Abfrageanforderung abgeschlossen ist. Dazu wird die Updatemethode des Pollers-Vorgangs aufgerufen. Es empfängt nur optional ein Objekt mit einer abortSignal-Eigenschaft von @azure/abort-controller AbortSignalLike.
pollUntilDone({ abortSignal?: AbortSignalLike })

Gibt eine Zusage zurück, die nach Abschluss des zugrunde liegenden Vorgangs aufgelöst wird.
stopPolling()

Verhindert, dass der Poller weiterhin abfragt.
toString()

Gibt eine serialisierte Version des Abrufvorgangs zurück, indem die toString-Methode des Vorgangs aufgerufen wird.

Details zum Konstruktor

Poller(PollOperation<TState, TResult>)

Ein Poller muss initialisiert werden, indem mindestens die grundlegenden Eigenschaften von PollOperation<TState, TResult>übergeben werden. Beim Schreiben einer Implementierung eines Pollers muss sich diese Implementierung mit der Initialisierung eines beliebigen benutzerdefinierten Zustands befassen, der über die grundlegende Definition des Pollers hinausgeht. Der grundlegende Poller geht davon aus, dass der Vorgang des Pollers bereits definiert wurde, zumindest seine grundlegenden Eigenschaften. Der folgende Code zeigt, wie Sie sich der Definition des Konstruktors eines neuen benutzerdefinierten Pollers nähern.

export class MyPoller extends Poller<MyOperationState, string> {
  constructor({
    // Anything you might need outside of the basics
  }) {
    let state: MyOperationState = {
      privateProperty: private,
      publicProperty: public,
    };

    const operation = {
      state,
      update,
      cancel,
      toString
    }

    // Sending the operation to the parent's constructor.
    super(operation);

    // You can assign more local properties here.
  }
}

Innerhalb dieses Konstruktors wird eine neue Zusage erstellt. Dies wird verwendet, um dem Benutzer mitzuteilen, wann der Abrufvorgang abgeschlossen ist (siehe pollUntilDone()). Die Resolve- und Reject-Methoden der Zusage werden auch intern verwendet, um zu steuern, wann alle Personen, die auf den Abschluss des Abrufs warten, aufgelöst oder abgelehnt werden sollen.

Im Konstruktor einer benutzerdefinierten Implementierung eines Pollers sollte jede serialisierte Version des Vorgangs eines vorherigen Abfragevorgangs in den Vorgang deserialisiert werden, der an den Basiskonstruktor gesendet wird. Beispiel:

export class MyPoller extends Poller<MyOperationState, string> {
  constructor(
    baseOperation: string | undefined
  ) {
    let state: MyOperationState = {};
    if (baseOperation) {
      state = {
        ...JSON.parse(baseOperation).state,
        ...state
      };
    }
    const operation = {
      state,
      // ...
    }
    super(operation);
  }
}

new Poller(operation: PollOperation<TState, TResult>)

Parameter

operation

PollOperation<TState, TResult>

Muss die grundlegenden Eigenschaften von PollOperation<State, TResult>enthalten.

Details zur Methode

cancelOperation({ abortSignal?: AbortSignalLike })

Versucht, den zugrunde liegenden Vorgang abzubrechen. Es empfängt nur optional ein Objekt mit einer abortSignal-Eigenschaft von @azure/abort-controller AbortSignalLike.

Wenn es erneut aufgerufen wird, bevor er abgeschlossen ist, wird ein Fehler ausgelöst.

function cancelOperation(options?: { abortSignal?: AbortSignalLike }): Promise<void>

Parameter

options

{ abortSignal?: AbortSignalLike }

Optionale Eigenschaften, die an die Updatemethode des Vorgangs übergeben werden.

Gibt zurück

Promise<void>

getOperationState()

Gibt den Status des Vorgangs zurück. Obwohl TState innerhalb einer beliebigen Erweiterung der Poller-Klasse derselbe Typ ist, können Implementierungen der Poller-Klasse anpassen, was für die Öffentlichkeit freigegeben wird, indem sie eine eigene Version der getOperationState Methode schreiben und zwei Typen definieren, einen, der den internen Zustand des Pollers darstellt, und einen öffentlichen Typ, der eine sichere Teilmenge der Eigenschaften des internen Zustands darstellt. Ihre Definition von getOperationState kann dann ihren öffentlichen Typ zurückgeben.

Beispiel:

// Let's say we have our poller's operation state defined as:
interface MyOperationState extends PollOperationState<ResultType> {
  privateProperty?: string;
  publicProperty?: string;
}

// To allow us to have a true separation of public and private state, we have to define another interface:
interface PublicState extends PollOperationState<ResultType> {
  publicProperty?: string;
}

// Then, we define our Poller as follows:
export class MyPoller extends Poller<MyOperationState, ResultType> {
  // ... More content is needed here ...

  public getOperationState(): PublicState {
    const state: PublicState = this.operation.state;
    return {
      // Properties from PollOperationState<TResult>
      isStarted: state.isStarted,
      isCompleted: state.isCompleted,
      isCancelled: state.isCancelled,
      error: state.error,
      result: state.result,

      // The only other property needed by PublicState.
      publicProperty: state.publicProperty
    }
  }
}

Sie können dies in den Tests dieses Repositorys sehen, wechseln Sie zur Datei:../test/utils/testPoller.ts und suchen Sie nach der getOperationState-Implementierung.

function getOperationState(): TState

Gibt zurück

TState

getResult()

Gibt den Ergebniswert des Vorgangs zurück, unabhängig vom Zustand des Pollers. Je nach Implementierung kann der endgültige TResult-Wert nicht definiert oder unvollständig zurückgegeben werden.

function getResult(): TResult | undefined

Gibt zurück

TResult | undefined

isDone()

Gibt true zurück, wenn der Poller die Abfrage abgeschlossen hat.

function isDone(): boolean

Gibt zurück

boolean

isStopped()

Gibt true zurück, wenn der Poller beendet wurde.

function isStopped(): boolean

Gibt zurück

boolean

onProgress((state: TState) => void)

Ruft den bereitgestellten Rückruf auf, nachdem jede Abfrage abgeschlossen ist, und sendet den aktuellen Zustand des Abfragevorgangs. Es gibt eine Methode zurück, die verwendet werden kann, um den Empfang von Updates für die angegebene Rückruffunktion zu beenden.

function onProgress(callback: (state: TState) => void): CancelOnProgress

Parameter

callback

(state: TState) => void

Gibt zurück

CancelOnProgress

poll({ abortSignal?: AbortSignalLike })

Gibt eine Zusage zurück, die aufgelöst wird, sobald eine einzelne Abfrageanforderung abgeschlossen ist. Dazu wird die Updatemethode des Pollers-Vorgangs aufgerufen. Es empfängt nur optional ein Objekt mit einer abortSignal-Eigenschaft von @azure/abort-controller AbortSignalLike.

function poll(options?: { abortSignal?: AbortSignalLike }): Promise<void>

Parameter

options

{ abortSignal?: AbortSignalLike }

Optionale Eigenschaften, die an die Updatemethode des Vorgangs übergeben werden.

Gibt zurück

Promise<void>

pollUntilDone({ abortSignal?: AbortSignalLike })

Gibt eine Zusage zurück, die nach Abschluss des zugrunde liegenden Vorgangs aufgelöst wird.

function pollUntilDone(pollOptions?: { abortSignal?: AbortSignalLike }): Promise<TResult>

Parameter

pollOptions

{ abortSignal?: AbortSignalLike }

Gibt zurück

Promise<TResult>

stopPolling()

Verhindert, dass der Poller weiterhin abfragt.

function stopPolling()

toString()

Gibt eine serialisierte Version des Abrufvorgangs zurück, indem die toString-Methode des Vorgangs aufgerufen wird.

function toString(): string

Gibt zurück

string