Freigeben über

Zugreifen auf SharePoint-Daten über Add-Ins mithilfe der domänenübergreifenden Bibliothek

  • Artikel

Wenn Sie SharePoint-Add-Ins erstellen, müssen Sie in der Regel Daten aus verschiedenen Quellen integrieren. Aus Sicherheitsgründen verhindern Blockierungsmechanismen aber die Kommunikation mit mehreren Domänen gleichzeitig. Diese Sicherheitsmechanismen sind in den meisten Browsern implementiert, weshalb es schwierig oder unmöglich ist, clientseitige Aufrufe über Domänen hinweg zu tätigen.

Wenn ein Benutzer eine Seite von Ihrem Domänen-Add-In anfordert, ist die clientseitige Kommunikation nur an diese Domäne gebunden. Das Add-In kann clientseitige Anrufe der Seite nur an andere Ressourcen in derselben Domäne ausstellen. Add-Ins erfordern jedoch in der Regel Ressourcen aus anderen Domänen, z. B. der SharePoint-Domäne, um deren Szenarien zu erfüllen. In dem Code auf Ihrer Seite können Sie versuchen, eine Anforderung an die SharePoint-Domäne auszustellen, die vom Browser blockiert wird. In der Regel wird der Fehler Zugriff verweigert angezeigt. Der Fehler bedeutet nicht zwangsläufig, dass Sie keine Berechtigungen für die angeforderte Ressource haben, sondern höchstwahrscheinlich, dass Sie nicht einmal eine Anforderung für die erwähnten Ressourcen ausstellen können.

Wenn Sie die domänenübergreifende Bibliothek verwenden, können die Webseiten in Ihrem Add-In auf Daten in Ihrer Add-In-Domäne und der SharePoint-Domäne zugreifen. Die domänenübergreifende Bibliothek ist eine clientseitige Alternative in Form einer auf der SharePoint-Website gehosteten JavaScript-Datei (SP.RequestExecutor.js), auf die Sie in Ihrem Remote-Add-In verweisen können. Mit der domänenübergreifenden Bibliothek können Sie mit mehr als einer Domäne auf der Remote-Add-In-Seite über einen Proxy interagieren. Dies ist eine gute Wahl, wenn Sie den Add-In-Code im Client statt auf dem Server ausführen möchten oder wenn Konnektivitätshindernisse wie Firewalls zwischen SharePoint und Ihrer Remote-Infrastruktur vorhanden sind.

Sie können auf Daten im Hostweb zugreifen; Sie können beispielsweise unabhängig von Ihrem Add-In auf Listen zugreifen, mit denen Endbenutzer interagieren. Oder Sie können im Add-In-Web auf Daten zugreifen, z. B. auf Listen, die speziell für Ihr Add-In bereitgestellt werden. Add-Ins können auch auf andere Websitesammlungen und Websites zugreifen, solange das Add-In über mandantenbereichsbezogene Berechtigungen verfügt und als Batchinstallation mithilfe des Add-In-Katalogs bereitgestellt wurde.

Hinweis

In diesem Thema bezieht sich Add-In-Domäne auf die Domäne, die die Add-In-Seiten hostet. Dies kann die Domäne einer Remotewebanwendung in einem vom Anbieter gehosteten Add-In sein, Add-In-Seiten können sich jedoch auch in SharePoint im Ad-In-Web befinden und Aufrufe der Hostwebdomäne ausführen. Im letzteren Szenario ist die Add-In-Domäne die Domäne des Add-In-Webs.

Das wichtigste Beispiel in diesem Artikel zeigt, wie ein Add-In erstellt wird, das Daten im Add-In-Web liest und diese auf einer Webseite anzeigt. Im Abschnitt nächste Schritte werden weitere Szenarien gezeigt, die auf dem wichtigsten Beispiel basieren.

Voraussetzungen

Um diese Beispiele auszuführen, benötigen Sie Folgendes:

Lesen von Daten im Add-In-Web unter Verwendung der domänenübergreifenden Bibliothek

In diesem Beispiel wurde eine einfache Webseite außerhalb von SharePoint gehostet, die einen Representational State Transfer- (REST-)Endpunkt benötigt, um Daten einer SharePoint-Website (Add-In-Web) zu lesen. Da die domänenübergreifende Bibliothek ein Add-In-Web erfordert, sollten Sie mit diesem Szenario beginnen.

Gehen Sie wie folgt vor, um Daten im Add-In-Web zu lesen:

  1. Erstellen Sie ein SharePoint-Add-In-Projekt und Webprojekte.

  2. Erstellen Sie Listenelemente im Add-In-Web. Mit diesem Schritt stellen Sie auch sicher, dass ein Add-In-Web erstellt wird, wenn Benutzer das Add-In bereitstellen.

  3. Erstellen Sie eine Add-In-Seite, die mithilfe der domänenübergreifenden Bibliothek die Listenelemente liest.

Die folgende Abbildung zeigt eine Webseite, die Daten im Add-In-Web anzeigt.

Beispielergebnisbildschirm für domänenübergreifende Leseelemente

So erstellen Sie ein SharePoint-Add-In und Webprojekte

  1. Öffnen Sie Visual Studio als Administrator. (Klicken Sie dazu im Menü Start mit der rechten Maustaste auf das Visual Studio-Symbol, und wählen Sie Als Administrator ausführen aus.)

  2. Erstellen Sie ein neues Projekt unter Verwendung der Vorlage SharePoint-Add-In. Die Vorlage Add-In für SharePoint in Visual Studio befindet sich unter Vorlagen > Visual C# > Office SharePoint > Add-Ins.

  3. Geben Sie die URL der SharePoint-Website an, die Sie für das Debugging verwenden möchten.

  4. Wählen Sie als Hostingoption für Ihr Add-In Von Anbieter gehostet aus.

    Hinweis

    Sie können auch die domänenübergreifende Bibliothek in einem von SharePoint gehosteten Add-In verwenden. In einem in SharePoint-gehosteten Add-In befindet sich die Add-In-Seite jedoch bereits im Add-In-Web. In diesem Fall ist nicht die domänenübergreifende Bibliothek zum Lesen der Listenelemente erforderlich. Ein Beispiel für ein in SharePoint gehostetes Add-In, das Daten im Hostweb liest, finden Sie unter Verwenden der domänenübergreifenden Bibliothek in einem in SharePoint-gehosteteten Add-In (REST) oder unter Zugreifen auf Daten aus dem Hostweb weiter unten in diesem Artikel.

So erstellen Sie Listenelemente im Add-In-Web

  1. Klicken Sie im Projektmappen-Explorer auf das SharePoint-Add-In-Projekt. Wählen Sie Hinzufügen > Neues Element.

  2. Wählen Sie Visual C#-Elemente > Office/SharePoint > Liste aus. Legen Sie den Namen der Liste auf Ankündigungen fest.

  3. Doppelklicken Sie auf Ankündigungen > Elements.xml. Fügen Sie die folgenden XML-Knoten als untergeordnete Objekte des ListInstance-Elements ein.

    <Data>
    <Rows>
        <Row>
            <Field Name="Title">Lorem ipsum 1</Field>
            <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
        </Row>
        <Row>
            <Field Name="Title">Lorem ipsum 2</Field>
            <Field Name="Body">Sed ut perspiciatis, unde omnis iste...</Field>
        </Row>
    </Rows>
</Data>

So erstellen Sie eine Add-In-Seite, die die domänenübergreifende Bibliothek verwendet

  1. Doppelklicken Sie im Projektmappen-Explorer auf die Datei Default.aspx.

  2. Kopieren Sie den folgenden Code, und fügen Sie ihn in die die Datei "Default.aspx" ein. Der Code führt die folgenden Aufgaben aus:

    • Laden der jQuery-Bibliothek aus dem Microsoft CDN.

    • Stellt einen Platzhalter für das Ergebnis bereit.

    • Extrahiert die Add-In-Web-URL aus der Abfragezeichenfolge.

    • Lädt das JavaScript für die domänenübergreifende Bibliothek mithilfe der getScript-Funktion in jQuery.

      Die Funktion lädt die erforderlichen Ressourcen und geht dann zur angegebenen Funktion über. Sie stellt sicher, dass die domänenübergreifende Bibliothek geladen und verfügbar für den nachfolgenden Code ist.

    • Instantiiert das RequestExecutor-Objekt. Standardmäßig verwendet RequestExecutor das Add-In-Web als Kontextwebsite.

      Hinweis

      (REST) oder das Objekt (JSOM). Weitere Informationen zu AppContextSite finden Sie unter Zugreifen auf Daten in einem Hostweb weiter unten in diesem Artikel.

    • Gibt einen REST-Aufruf an den Listenelementendpunkt aus.

    • Sorgt für einen erfolgreichen Abschluss und zeigt die Listenelemente auf der Webseite an.

    • Behandelt Fehler und zeigt die Fehlermeldung auf der Webseite an.

  
<html>
    <head>
        <title>Cross-domain sample</title>
    </head>
    <body>
        <!-- This is the placeholder for the announcements -->
        <div id="renderAnnouncements"></div>
        <script 
            type="text/javascript" 
            src="//ajax.aspnetcdn.com/ajax/jQuery/jquery-1.7.2.min.js">
        </script>
        <script type="text/javascript">
          var hostweburl;
          var appweburl;

          // Load the required SharePoint libraries
          $(document).ready(function () {
            //Get the URI decoded URLs.
            hostweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPHostUrl")
            );
            appweburl =
                decodeURIComponent(
                    getQueryStringParameter("SPAppWebUrl")
            );

            // resources are in URLs in the form:
            // web_url/_layouts/15/resource
            var scriptbase = hostweburl + "/_layouts/15/";

            // Load the js files and continue to the successHandler
            $.getScript(scriptbase + "SP.RequestExecutor.js", execCrossDomainRequest);
          });

          // Function to prepare and issue the request to get
          //  SharePoint data
          function execCrossDomainRequest() {
            // executor: The RequestExecutor object
            // Initialize the RequestExecutor with the add-in web URL.
            var executor = new SP.RequestExecutor(appweburl);

            // Issue the call against the add-in web.
            // To get the title using REST we can hit the endpoint:
            //      appweburl/_api/web/lists/getbytitle('listname')/items
            // The response formats the data in the JSON format.
            // The functions successHandler and errorHandler attend the
            //      sucess and error events respectively.
            executor.executeAsync(
                {
                  url:
                      appweburl +
                      "/_api/web/lists/getbytitle('Announcements')/items",
                  method: "GET",
                  headers: { "Accept": "application/json; odata=verbose" },
                  success: successHandler,
                  error: errorHandler
                }
            );
          }

          // Function to handle the success event.
          // Prints the data to the page.
          function successHandler(data) {
            var jsonObject = JSON.parse(data.body);
            var announcementsHTML = "";

            var results = jsonObject.d.results;
            for (var i = 0; i < results.length; i++) {
              announcementsHTML = announcementsHTML +
                  "<p><h1>" + results[i].Title +
                  "</h1>" + results[i].Body +
                  "</p><hr>";
            }

            document.getElementById("renderAnnouncements").innerHTML =
                announcementsHTML;
          }

          // Function to handle the error event.
          // Prints the error message to the page.
          function errorHandler(data, errorCode, errorMessage) {
            document.getElementById("renderAnnouncements").innerText =
                "Could not complete cross-domain call: " + errorMessage;
          }

          // Function to retrieve a query string value.
          // For production purposes you may want to use
          //  a library to handle the query string.
          function getQueryStringParameter(paramToRetrieve) {
            var params =
                document.URL.split("?")[1].split("&amp;");
            var strParams = "";
            for (var i = 0; i < params.length; i = i + 1) {
              var singleParam = params[i].split("=");
              if (singleParam[0] == paramToRetrieve)
                return singleParam[1];
            }
          }
        </script>
    </body>
</html>

So erstellen Sie die Lösung und führen sie aus

  1. Wählen Sie die F5-Taste.

    Hinweis

    Wenn Sie F5 wählen, erstellt Visual Studio die Lösung, stellt das Add-In bereit und öffnet die Berechtigungsseite für das Add-In.

  2. Wählen Sie die Schaltfläche Vertrauen.

  3. Wählen Sie auf der Seite Websiteinhalte das Add-In-Symbol.

Wenn Sie Codebeispiele zum Herunterladen bevorzugen, können Sie die Folgendes aus dem Codekatalog abrufen:

Problembehandlung für die Lösung

Wenn die folgende Fehlermeldung auftritt... Versuchen Sie Folgendes...
„Bei dem Versuch, auf Ihre Website zuzugreifen, gab es Probleme.“ Es gibt zwar eine Schaltfläche zur Fehlerbehebung, aber sie löst nicht das Problem. Möglicherweise haben Sie ein bekanntes Problem mit Sicherheitszonen in Internet Explorer. Weitere Informationen dazu finden Sie unter Arbeiten mit der domänenübergreifenden Bibliothek in verschiedenen Internet Explorer-Sicherheitszonen in Add-Ins für SharePoint.
„Die erforderlichen Funktionen werden von Ihrem Browser nicht unterstützt.“ Stellen Sie sicher, dass Sie IE 8 oder höher, bzw. einen anderen modernen Browser verwenden. Stellen Sie bitte ferner sicher, dass das Metatag „X-UA-Compatible“ auf „IE = 8“ oder höher festgelegt ist. Die domänenübergreifende Bibliothek erfordert den Dokumentmodus IE 8 oder höher. In einigen Szenarien ist der Dokumentmodus standardmäßig auf IE7 festgelegt. Sie können die Internet Explorer-Entwicklertools verwenden, um den Dokumentmodus Ihrer Seite zu ermitteln und zu ändern. Weitere Informationen finden Sie unter Definieren der Dokumentkompatibilität.
„Typ“ wurde nicht definiert. Außerdem verwendet Ihr Add-In das JavaScript-Objektmodell (JSOM). Das JSOM verwendet die Type.registerNamespace-Methode in der Microsoft Ajax-Bibliothek, um den SP -Namespace zu registrieren. Verwenden Sie den folgenden Code, um einen Verweis von Ihrer Webseite auf die Microsoft Ajax-Bibliothek zu erstellen:

HTML <script type="text/javascript" src="//ajax.aspnetcdn.com/ajax/4.0/1/MicrosoftAjax.js"></script>

Nächste Schritte: Weitere Szenarien mit der domänenübergreifenden Bibliothek

Dieser Artikel zeigt, wie Sie eine Anforderungen an einen REST-Endpunkten senden, um Daten im Add-In-Web über eine Add-In-Seite zu lesen, die nicht auf SharePoint gehostet ist. Sie können auch die folgenden Szenarien untersuchen und Details zur domänenübergreifenden Bibliothek anzeigen.

Verwenden des JSOM zum Lesen von Daten im Add-In-Web

Sie möchten vielleicht lieber das JSOM anstelle von REST verwenden, um Daten aus dem Add-In-Web anzufordern. Sie müssen zusätzliche Tasks ausführen, um die domänenübergreifende Bibliothek zusammen mit JSOM verwenden zu können:

  • Verweisen Sie auf SharePoint JSOM auf Ihrer Add-In-Seite.

  • Initialisieren Sie das ProxyWebRequestExecutorFactory-Objekt, und legen Sie es als die Factory des Kontextobjekts fest.

  • Greifen Sie auf die SharePoint-Objekte zu, um Daten in der Liste zu lesen.

  • Laden Sie die Objekte in den Kontext, und führen Sie die Abfrage aus.

Ein Codebeispiel, das zeigt, wie Sie die Aufgaben ausführen, finden Sie unter SharePoint-Add-in-JSOM-CrossDomain.

Weitere Informationen zur Verwendung des JSOM finden Sie unter Verwenden des JavaScript-Objektmodells (JSOM) in Add-Ins für SharePoint.

Zugreifen auf Daten in einem Hostweb

In dem Beispiel auf dieser Seite wird gezeigt,wie Daten aus dem Add-In-Web gelesen werden. Dies kann wunderbar als Startbeispiel verwendet werden, da die domänenübergreifende Bibliothek anfänglich das Add-In als Kontextwebsite verwendet. Es gibt jedoch viele Szenarien, in denen Sie auf Daten im Hostweb zugreifen möchten. Zum Zugreifen auf Daten im Hostweb sind einige Aufgaben erforderlich:

  • Legen Sie das Hostweb als Kontextwebsite für die domänenübergreifende Bibliothek fest.

  • Stellen Sie ausreichende Berechtigungen für das Add-In bereit.

Sie können die Kontextwebsite ändern, indem Sie den AppContextSite-Endpunkt (REST) oder das Objekt (JSOM) verwenden. Das folgende Codebeispiel zeigt, wie die Kontextwebsite mithilfe des JSOM-Endpunkts geändert wird:

executor.executeAsync(
    {
        url:
            appweburl +
            "/_api/SP.AppContextSite(@target)/web/title?@target='" +
            hostweburl + "'",
        method: "GET",
        headers: { "Accept": "application/json; odata=verbose" },
        success: successHandler,
        error: errorHandler
    }
);

Das folgende Codebeispiel zeigt, wie die Kontextwebsite mit JSOM geändert wird:

context = new SP.ClientContext(appweburl);
factory = new SP.ProxyWebRequestExecutorFactory(appweburl);
context.set_webRequestExecutorFactory(factory);
appContextSite = new SP.AppContextSite(context, hostweburl);

this.web = appContextSite.get_web();
context.load(this.web);

Ihr Add-In hat standardmäßig Berechtigungen für das Add-In-Web, aber nicht für das Hostweb. Das folgende Beispiel zeigt einen Manifestabschnitt, der eine Berechtigungsanforderung zum Lesen von Daten aus dem Hostweb deklariert:

<AppPermissionRequests>
    <AppPermissionRequest 
        Scope="http://sharepoint/content/sitecollection/web" 
        Right="Read" />
</AppPermissionRequests>

Stellen Sie sicher, dass Sie eine Ressource im Add-In-Web erstellen (beispielsweise eine leere Seite oder Liste), um die Bereitstellung des Add-In-Webs zu erzwingen, die für eine Verwendung der domänenübergreifenden Bibliothek erforderlich ist.

Zugreifen auf Daten in allen Websitesammlungen

Dank der domänenübergreifenden Bibliothek können Sie auf Daten in allen Websitesammlungen desselben Mandanten zugreifen. Sie müssen aber einige Tasks ausführen, um websitesammlungsübergreifende auf Daten zugreifen zu können:

  • Fügen Sie eine Berechtigungsanforderung hinzu, um auf Daten im Mandanten zuzugreifen.

  • Wechseln Sie in Ihrem Code von der Kontextwebsite zu den Websitesammlungen, die Sie abfragen möchten.

  • Fügen Sie das Add-In zum Add-In-Katalog hinzu.

  • Stellen Sie das Add-In als mandantenbereichsbezogenes Add-In auf einer Website bereit. Ein Beispiel, wie Sie ein mandantenbereichsbezogenes Add-In bereitstellen, finden Sie in der Beschreibung des Codebeispiels Verwenden der domänenübergreifenden Bibliothek in einem mandantenbereichsbezogenen Add-In (REST).

Ihr Add-In benötigt auch Zugriffsberechtigungen für Daten aus dem Mandanten. Das folgende Beispiel zeigt einen Manifestabschnitt, der eine Berechtigungsanforderung zum Lesen von Daten aus dem Mandanten deklariert:

<AppPermissionRequests>
  <AppPermissionRequest 
    Scope="http://sharepoint/content/tenant" 
    Right="Read" />
</AppPermissionRequests>

Wenn Sie die Kontextwebsite in Ihrem Code wechseln möchten, verwenden Sie den AppContextSite-Endpunkt (REST) oder das Objekt (JSOM), genau so wie im Abschnitt Zugreifen auf Daten im Hostweb beschrieben.

Hier finden Sie zur Erinnerung Informationen zum REST-Endpunkt: /_api/SP.AppContextSite(@target)/web/title?@target='weburl', und ein Beispiel zur Instanziierung des Objekts in JSOM: appContextSite = new SP.AppContextSite(context, weburl);.

Als Entwickler können Sie nur mandantenbereichsbezogene Add-Ins aus dem Add-In-Katalog bereitstellen. Sie können einen Add-In-Katalog in Ihrer lokalen oder SharePoint Online-Umgebung bereitstellen. Das Hochladen Ihres Add-Ins in den Add-In-Katalog ist genau so einfach wie das Hochladen einer Datei in eine Dokumentbibliothek. Ausführliche Anweisungen finden Sie unter Verwenden des App-Katalogs zum Erstellen von benutzerdefinierten Geschäfts-Apps, die für Ihre SharePoint Online-Umgebung verfügbar sind.

Aus dem Add-In-Katalog können Sie das Add-In auf einer oder mehreren Websites im Mandanten bereitstellen. Da das Add-In über Berechtigungen zum Zugreifen auf Daten im Mandanten verfügt, muss die Bereitstellung nur auf einer Website erfolgen, um auf Daten im gesamten Mandanten zuzugreifen. Anweisungen zur Bereitstellung eines Add-Ins aus dem Add-In-Katalog finden Sie unter Bereitstellen eines benutzerdefinierten Add-Ins.

Wenn Sie einen Beispielcode herunterladen möchten, der den Zugriff auf Daten in allen Websitesammlungen zeigt, navigieren Sie zu Verwenden der domänenübergreifenden Bibliothek in einem mandantenbereichsbezogenen Add-In (REST).

Senden von Aufrufen in unterschiedlichen Sicherheitszonen

Die domänenübergreifende Bibliothek verwendet eine Proxyseite, die in einem IFrame auf der Add-In-Seite gehostet wird, um die Kommunikation zu ermöglichen. Wenn sich die Add-In-Seite und die SharePoint-Website in unterschiedlichen Sicherheitszonen befinden, können keine Autorisierungscookies gesendet werden. Wenn keine Autorisierungscookies vorhanden sind und das IFrame versucht, die Proxyseite zu laden, wird es an die SharePoint-Anmeldeseite weitergeleitet. Die SharePoint-Anmeldeseite kann aus Sicherheitsgründen nicht in einem IFrame enthalten sein. In den folgenden Szenarien kann die Bibliothek die Proxyseite nicht laden, und die Kommunikation mit SharePoint ist nicht möglich.

Es gibt aber eine Lösung für diesen Fall. Die Lösung ist das apphost-Muster, das darin besteht, die Add-In-Seiten in einer Seite zu verpacken, die im Add-In-Web gehostet ist. Das apphost-Muster eignet sich gut in Add-Ins, die die domänenübergreifende Bibliothek verwenden, selbst wenn keine offensichtlichen Sicherheitsgrenzen vorhanden sind. Weitere Informationen finden Sie unter Arbeiten mit der domänenübergreifenden Bibliothek in verschiedenen Internet Explorer-Sicherheitszonen in Add-Ins für SharePoint.

Zugreifen auf Daten über einen zusätzlichen Remotehost in einem von SharePoint gehosteten Add-In

Standardmäßig ist ein Von SharePoint gehostetes Add-In zulässig, um domänenübergreifende Aufrufe an das Hostweb zu senden, vorausgesetzt sie verfügt über die entsprechenden Berechtigungen. Ein Von SharePoint gehostetes Add-In kann aber auch einen Remotehost im AllowedRemoteHostUrl-Attribut ihres AppPrincipal angeben. Damit können Sie domänenübergreifende Aufrufe aus dem Add-In-Web und von beliebigen anderen Hosts senden.

Wenn Sie ein Codebeispiel eines von SharePoint gehosteten Add-Ins herunterladen möchten, das die domänenübergreifende Bibliothek verwendet, navigieren Sie zu Codebeispiel: Verwenden der domänenübergreifenden Bibliothek in einem von SharePoint gehosteten Add-In (REST).

Siehe auch