Client-API-Serverendpunkte und Cloudflüsse

$pages.ajax

Das $pages.ajax Objekt stellt eine generische HTTP-Anforderungsmethode bereit, die Sie zum Aufrufen serverseitiger Endpunkte von Ihrer Website verwenden. Verwenden Sie sie zum Aufrufen von Serverlogik, Cloudflüssen und anderen benutzerdefinierten /_api/ Endpunkten aus Clientskripts. Das $pages.ajax Objekt stellt eine generische HTTP-Anforderungsmethode bereit, die Sie zum Aufrufen serverseitiger Endpunkte von Ihrer Website verwenden. Verwenden Sie sie zum Aufrufen von Serverlogik, Cloudflüssen und anderen benutzerdefinierten /_api/ Endpunkten aus Clientskripts.

Jede Anforderung wird automatisch wie folgt behandelt:

  • Cross-Site Request Forgery (CSRF)-Token: Das Token wird abgerufen, wenn es zum ersten Mal benötigt, im Arbeitsspeicher zwischengespeichert und dem Header jeder Anforderung hinzugefügt wird. Sie müssen das Token nicht abrufen oder übergeben.
  • Anmeldeinformationen: Das Sitzungscookies ist in jeder Anforderung enthalten.
  • x-requested-with header: Dieser Header ist für jede Anforderung festgelegt XMLHttpRequest .

Anforderungsmethode

Sendet eine HTTP-Anforderung an die angegebene URL.

Syntax: $pages.ajax.request(options: object): Promise<AjaxResponse>
Gibt zurück: Eine Zusage , die in ein AjaxResponse -Objekt aufgelöst wird.

Die Zusage lehnt mit einem AjaxError-Objekt ab, wenn der Server einen Statuscode außerhalb des Bereichs 200-299 zurückgibt oder wenn das Netzwerk fehlschlägt. Abbruchfehler eines AbortSignal Objekts werden nicht in ein AjaxError Objekt eingeschlossen. Siehe "Abbrechen einer Anforderung".

Parameter der Anforderungsmethode

Der options Parameter akzeptiert die folgenden Eigenschaften.

Eigentum Type Erforderlich Description
url string Ja Ein relativer Pfad, z /_api/serverlogics/mylogic. B. eine absolute URL.
method string No Die HTTP-Methode: GET, , POST, PUT, , PATCHoder DELETE. Bei diesem Wert wird die Groß-/Kleinschreibung nicht beachtet. Der Standardwert ist GET , wenn Sie keinen Textkörper bereitstellen und POST einen Textkörper angeben.
body Objekt No Die Anforderungsnutzlast, die automatisch in JSON serialisiert wird. Der Text wird für alle Methoden gesendet, einschließlich GET. Eine GET Anforderung mit einem Textkörper ist nicht standardmäßig, und einige HTTP-Zwischenvermittler entfernen sie. Verwenden Sie daher einen Textkörper GET nur dann, wenn die von Ihnen aufgerufene API sie unterstützt.
params Objekt No Schlüssel-Wert-Paare, die als Abfragezeichenfolge an die URL angefügt werden. Werte werden in Zeichenfolgen konvertiert. Wenn die URL bereits eine Abfragezeichenfolge enthält, werden die Werte an sie angefügt.
headers Objekt No Weitere Kopfzeilen, die mit den Standardheadern zusammengeführt werden sollen. Sie können den CSRF-Header oder den x-requested-with Header nicht überschreiben.
signal AbortSignal No Ein Signal, das eine anforderung abbricht, die gerade ausgeführt wird. Siehe "Abbrechen einer Anforderung".

AjaxResponse-Objekt

Die request Methode wird in ein Objekt aufgelöst, das die folgenden Eigenschaften aufweist.

Eigentum Type Description
data Unbekannt Der analysierte Antworttext.
status Zahl Der HTTP-Statuscode.
ok boolesch True, wenn sich der Statuscode im Bereich von 200 bis 299 befindet. Da die request Methode für andere Statuscodes ablehnt, gilt dieser Wert für jede Antwort, in die die Methode aufgelöst wird.
headers Objekt Die Antwortheader als Schlüssel-Wert-Paare.

AjaxError-Objekt

Die request Methode lehnt mit einem Objekt ab, das die folgenden Eigenschaften aufweist.

Eigentum Type Description
name string Der Wert AjaxError. Überprüfen Sie diese Eigenschaft, um eine fehlgeschlagene Anforderung abgesehen von anderen Fehlern zu informieren.
message string Eine Beschreibung des Fehlers.
status Zahl Der HTTP-Statuscode. Der Wert ist 0 , wenn das Netzwerk fehlschlägt und keine Antwort empfangen wird.
body Unbekannt Der analysierte Antworttext, wenn der Server einen zurückgibt; andernfalls null.
requestId Zeichenfolge | undefiniert Die serverseitige Anforderungsablaufverfolgungs-ID aus dem x-ms-request-id Antwortheader. Schließen Sie diesen Wert ein, wenn Sie ein Problem melden.

Beispiele für Anforderungsmethoden

In den folgenden Beispielen erfahren Sie, wie Sie die Anforderungsmethode verwenden.

Beispiel Description
Aufrufen der Serverlogik mithilfe einer GET-Anforderung Übergibt Abfragezeichenfolgenparameter mithilfe einer GET-Anforderung an die Serverlogik.
Aufrufen der Serverlogik mithilfe einer POST-Anforderung Sendet einen Anforderungstext mithilfe einer POST-Anforderung an die Serverlogik.
Auslösen eines Cloudflusses Löst einen bei der Website registrierten Cloudfluss aus und behandelt die Ablaufantwort.
Aktualisieren einer Ressource mithilfe einer PUT-Anforderung Aktualisiert eine Serverressource durch Senden eines Anforderungstexts mit einer PUT-Anforderung.
Löschen einer Ressource mithilfe einer DELETE-Anforderung Löscht eine Serverressource mithilfe einer DELETE-Anforderung mit Abfragezeichenfolgenparametern.
Umgang mit Fehlern Erfasst und AjaxError protokolliert den Status, den Antworttext und die Anforderungs-ID.
Abbrechen einer Anforderung Erläutert, wie eine AbortSignal Anforderung abgebrochen wird und wie Abbruchfehler zurückgegeben werden.
Abbrechen einer Anforderung nach einer festen Dauer Wird AbortSignal.timeout verwendet, um eine Anforderung nach einer maximalen Wartezeit abzubrechen.
Abbrechen einer Anforderung, wenn eine Komponente entfernt wird Verwendet eine AbortController Anforderung, um eine Anforderung abzubrechen, wenn die zugehörige Komponente entfernt wird.
Abbrechen einer vorherigen Anforderung Bricht eine unfertige Anforderung ab, bevor Sie einen Ersatz starten, sodass veraltete Antworten nicht in der Reihenfolge ankommen.

Aufrufen der Serverlogik mithilfe einer GET-Anforderung

In diesem Beispiel werden Abfragezeichenfolgenparameter an die Serverlogik übergeben.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'GET',
      url: '/_api/serverlogics/getweather',
      params: { city: 'Seattle' }
    });
    console.log(response.data);
});

Aufrufen der Serverlogik mithilfe einer POST-Anforderung

In diesem Beispiel wird ein Anforderungstext an die Serverlogik gesendet.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'POST',
      url: '/_api/serverlogics/createorder',
      body: { productId: 'abc123', quantity: 2 }
    });
    console.log(response.data);
});

Auslösen eines Cloudflusses

Power Pages Designstudio generiert die Cloudfluss-URL, wenn Sie den Fluss bei der Website registrieren.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const response = await $pages.ajax.request({
      method: 'POST',
      url: '/_api/cloudflow/v1.0/trigger/aaaaaaaa-0000-1111-2222-bbbbbbbbbbbb',
      body: { Location: 'Seattle' }
    });

    // The data property is null when the flow has no Response action and returns 202 Accepted.
    // The data property contains the flow output when the flow has a Response action and returns 200 OK.
    if (response.data) {
      console.log(response.data);
    }
});

Aktualisieren einer Ressource mithilfe einer PUT-Anforderung

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.ajax.request({
      method: 'PUT',
      url: '/_api/serverlogics/updateprofile',
      body: { displayName: 'New Name' }
    });
});

Löschen einer Ressource mithilfe einer DELETE-Anforderung

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    await $pages.ajax.request({
      method: 'DELETE',
      url: '/_api/serverlogics/deleteitem',
      params: { id: '99' }
    });
});

Fehler behandeln

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    try {
      const response = await $pages.ajax.request({
        method: 'POST',
        url: '/_api/serverlogics/createorder',
        body: { productId: 'abc123', quantity: 2 }
      });
      console.log('Order created:', response.data);
    } catch (err) {
      if (err.name === 'AjaxError') {
        console.error(`Request failed with status ${err.status}`);
        console.error('Response body:', err.body);
        // Provide err.requestId to support for server-side tracing.
        if (err.requestId) {
          console.error('Request ID:', err.requestId);
        }
      } else {
        throw err;
      }
    }
});

Anforderung abbrechen

Die signal Eigenschaft akzeptiert ein AbortSignal-Objekt . Wenn das Signal abgebrochen wird, wird die laufende Anforderung abgebrochen, und die Zusage lehnt mit einem Abbruchfehler ab. Dieser Fehler wird nicht in ein AjaxError-Objekt eingeschlossen, und seine name Eigenschaft ist CanceledError. Behandeln Sie diesen Fehler nicht als fehlgeschlagene Anforderung.

Abbrechen einer Anforderung nach einer festen Dauer

Verwenden Sie die AbortSignal.timeout Methode, um eine maximale Wartezeit festzulegen, ohne einen Controller zu verwalten.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    try {
      const response = await $pages.ajax.request({
        method: 'GET',
        url: '/_api/serverlogics/slowlogic',
        signal: AbortSignal.timeout(5000) // Cancel after 5 seconds.
      });
      console.log(response.data);
    } catch (err) {
      // A timeout is reported as a CanceledError. The underlying DOMException, which has
      // the name TimeoutError, is available on err.cause when you need to tell a timeout
      // apart from a manual cancellation.
      if (err.name === 'CanceledError') {
        if (err.cause?.name === 'TimeoutError') {
          console.warn('Request timed out.');
        } else {
          console.warn('Request was canceled.');
        }
      } else {
        // Handle server and network failures.
        console.error(err);
      }
    }
});

Abbrechen einer Anforderung, wenn eine Komponente entfernt wird

Wenn eine Anforderung an den Lebenszyklus einer Komponente gebunden ist, brechen Sie die Anforderung ab, wenn die Komponente entfernt wird, damit Ihr Code keine Komponente aktualisiert, die nicht mehr vorhanden ist.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    const controller = new AbortController();

    $pages.ajax.request({
      method: 'GET',
      url: '/_api/serverlogics/getdata',
      signal: controller.signal
    })
    .then(response => {
      // Update the UI with response.data.
    })
    .catch(err => {
      if (err.name !== 'CanceledError') {
        // Handle actual errors and ignore intentional cancellations.
        console.error(err);
      }
    });

    // Call this function from your cleanup logic, such as when the component
    // is removed from the page.
    const dispose = () => {
        controller.abort();
    };
});

Abbrechen einer vorherigen Anforderung

Wenn jemand eine neue Anforderung auslöst, bevor die vorherige Anforderung abgeschlossen ist, z. B. wenn sie in ein Suchfeld eingeben, brechen Sie die vorherige Anforderung ab, damit veraltete Antworten nicht in der Reihenfolge ankommen.

Microsoft.PowerPages.onPagesClientApiReady(async function ($pages) {
    let controller = null;

    async function search(query) {
      if (controller) {
        controller.abort(); // Cancel the previous request.
      }
      controller = new AbortController();

      try {
        const response = await $pages.ajax.request({
          method: 'GET',
          url: '/_api/serverlogics/search',
          params: { q: query },
          signal: controller.signal
        });
        console.log('Results:', response.data);
      } catch (err) {
        if (err.name !== 'CanceledError') {
          console.error(err);
        }
      }
    }

    // Run a search each time someone types in the search box.
    const searchBox = document.querySelector('#searchBox');

    if (searchBox) {
        searchBox.addEventListener('input', (e) => search(e.target.value));
    }
});