Verbinden mit SharePoint-APIs

In Ihren SharePoint-Framework-Lösungen möchten Sie wahrscheinlich mit in SharePoint gespeicherten Daten interagieren. SharePoint bietet eine umfassende Auswahl von APIs, die auf unterschiedliche Weisen verwendet werden können. In diesem Artikel wird beschrieben, über welche Optionen Sie verfügen, wie sie funktionieren und was ihre Vor- und Nachteile sind.

Verbindung mit der SharePoint-API mit dem SPHttpClient

SharePoint-Framework bietet den SPHttpClient, den Sie zum Herstellen einer Verbindung mit SharePoint-REST-APIs verwenden können. Eine sofort einsatzbereite Instanz des SPHttpClient steht im Webpart/Erweiterungskontext zur Verfügung; diese können Sie zum Ausführen von verschiedenen Webanforderungen verwenden. Der folgende Codeausschnitt zeigt, wie Sie den SPHttpClient verwenden, um den Titel der aktuellen Website abzurufen:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`, SPHttpClient.configurations.v1)
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: {Title: string}): void => {
    console.log(web.Title);
  });

Der SPHttpClient bietet die grundlegenden Funktionen zur Durchführung der am häufigsten verwendeten Webanforderungen. Außerdem können Sie Ihre Anforderung konfigurieren, indem Sie beispielsweise Anforderungsheader angeben. Wenn Sie zum Beispiel eine Webanforderung ausgeben möchten, ohne Metadaten abzurufen, würden Sie den folgenden Code verwenden:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata.metadata=none']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Überlegungen zur Verwendung des SPHttpClient

Bei der Verwendung des SPHttpClient gilt es ein paar Dinge zu berücksichtigen.

OData v4.0

Standardmäßig verwendet der SPHttpClient die OData v4-Spezifikation, die die Verwendung von odata.metadata anstelle von odata für die Verwaltung der Antwortmetadaten voraussetzt. Wenn Sie die odata-Richtlinie im OData v4-Modus verwenden, erhalten Sie eine Fehlermeldung wie z. B.: Der HTTP-Header ACCEPT ist nicht vorhanden oder sein Wert ist ungültig.. Es ist möglich, den SPHttpClient auf den OData v3.0-Modus festzulegen, indem Der Anforderungsheader odata-version auf einen leeren Wert festgelegt wird:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata=nometadata'],
        ['odata-version', '']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Authentifizierungscookies

Im SharePoint-Framework gibt es eine Reihe von Klassen für die Ausführung von Webanforderungen. Zwei davon sind SPHttpClient und HttpClient. Zu den Unterschieden zwischen dem SPHttpClient und HttpClient gehört, dass der SPHttpClient bei der Ausstellung von Webanforderungen Authentifizierungscookies enthält. Da SharePoint-APIs nicht anonym sind, müssen Sie Authentifizierungsinformationen angeben, andernfalls erhalten Sie die Antwort „401 – Nicht autorisiert“. Da der HttpClient in seinen Anforderungen keine Authentifizierungscookies enthält, schlagen Ihre Anforderungen mit dem Fehler „401 – Nicht autorisiert“ fehl, wenn Sie ihn zum Aufrufen der REST-APIs verwenden.

Teil des SharePoint-Frameworks

Der SPHttpClient ist Teil des SharePoint-Frameworks, und Sie benötigen keine zusätzlichen Abhängigkeiten für die Verwendung. Er ist bereits auf der Seite verfügbar. Daher verursacht dessen Verwendung keinen zusätzlichen Leistungsoverhead während der Laufzeit.

Raw-REST-Abfragen sind fehleranfällig.

Der SPHttpClient bietet grundlegende Unterstützung für die Kommunikation mit der SharePoint-REST-API. Wenn Ihre Anwendungen komplexere GET-Anforderungen und POST-Anforderungen benötigen oder erweiterte Funktionen wie zum Beispiel Batchverarbeitung verwenden, werden Sie schnell feststellen, dass die Verwendung des SPHttpClient mühselig und fehleranfällig ist. In solchen Fällen sollten Sie eine Alternative verwenden, z. B. die PnPjs-Bibliothek, die Ihnen eine Fluent-API bietet, die von TypeScript auf Richtigkeit überprüft werden kann.

Verbinden mit SharePoint über PnPjs

PnPjs ist eine Open-Source-JavaScript-Bibliothek für die Kommunikation mit SharePoint und Office 365. Sie stellt eine Fluent-API bereit, die es Ihnen ermöglicht, SharePoint- und Microsoft 365-REST-APIs ganz einfach auf typsichere Weise zu nutzen. Um den Titel der aktuellen Website mit PnPjs abzurufen, würden Sie den folgenden Code ausführen:

const web = await sp.web
  .select('Title')
  .get<{Title: string;}>();
console.log(web.Title);

Hinweis

PnPJS ist eine Open-Source-Lösung mit aktiver Community, die Unterstützung dafür bietet. Es gibt keine SLA für den Support des Open-Source-Tools durch Microsoft.

Beachten Sie, wie viel weniger ausführlich der Code im Vergleich mit dem SharePoint-Framework-SPHttpClient ist und wie alle Elemente der Anforderungen, mit Ausnahme der Namen der abzurufenden Eigenschaften, stark typisiert sind, sodass das Risiko von Runtimefehlern reduziert wird.

Weitere Informationen zum Einrichten und Verwenden von PnPjs im SharePoint-Framework finden Sie in der PnPjs-Dokumentation unter https://pnp.github.io/pnpjs/.

Überlegungen zur Verwendung von PnPjs

Bei der Entscheidung, ob Sie PnPjs verwenden sollten oder nicht, gibt es einige Aspekte, die Sie berücksichtigen sollten.

Raw-REST-Abfragen sind fehleranfällig.

Das Ausstellen von Raw-REST-Anforderungen über den SPHttpClient ist fehleranfällig. Insbesondere wenn Ihre Anwendung POST-Abfragen ausführen muss oder Sie einige der erweiterten Funktionen wie Batchverarbeitung verwenden möchten, ist die Zusammenstellung der richtigen Anforderungen und die Analyse der Antworten mühselig. Ganz zu schweigen davon, dass die einzige Möglichkeit zum Überprüfen der Richtigkeit von Anforderungen die Ausführung von Code im Browser ist. Mit PnPjs können Sie mit SharePoint-APIs auf typsichere Weise kommunizieren und die erweiterten Funktionen der SharePoint-API ganz einfach verwenden, sodass Sie sich auf das Erstellen Ihrer Anwendung konzentrieren können, statt ihre Anforderungen zu testen.

Open-Source-Projekt

PnPjs ist ein Open-Source-Projekt, das von der SharePoint-Community verwaltet wird. Es gibt keine SLA für die Verwendung von PnPjs in Ihren Lösungen und der Support von Microsoft unterstützt Sie nicht bei möglichen Problemen, wenn diese durch PnPjs verursacht werden. Unter dem Gesichtspunkt ist jedoch zu beachten, dass PnPjs aktiv weiterentwickelt wird und die Community schnell auf alle Probleme und Fragen reagiert.

Zusätzliche Abhängigkeit

PnPjs ist eine zusätzliche Abhängigkeit, die Sie zum Projekt hinzufügen und mit der Zeit verwalten müssen. Sie müssen die Updates im Auge behalten und das Projekt bei Bedarf aktualisieren. Die Community hinter PnPjs informiert regelmäßig über den Status der aktuellen Arbeit, anstehende Veröffentlichungen und etwaige Auswirkungen eines Upgrades auf die neuere Version.

Zusätzliche Nutzlast

PnPjs stellt umfassende Funktionen für die Kommunikation mit SharePoint-APIs bereit. Die Bibliothek unterstützt selektive Importe, sodass mit einer vorsichtigen Zusammenstellung die Gesamtauswirkungen auf die Größe Ihres Pakets verringert werden können. Weitere Informationen finden Sie in der Dokumentation unter https://pnp.github.io/pnpjs/.

  • Last updated on