Teilen über

Kopieren von Daten aus SharePoint Online-Listen mithilfe von Azure Data Factory oder Azure Synapse Analytics

  • Artikel

GILT FÜR: Azure Data Factory Azure Synapse Analytics

Tipp

Testen Sie Data Factory in Microsoft Fabric, eine All-in-One-Analyselösung für Unternehmen. Microsoft Fabric deckt alle Aufgaben ab, von der Datenverschiebung bis hin zu Data Science, Echtzeitanalysen, Business Intelligence und Berichterstellung. Erfahren Sie, wie Sie kostenlos eine neue Testversion starten!

In diesem Artikel wird beschrieben, wie Sie Daten aus SharePoint Online-Listen mithilfe der Kopieraktivität in Azure Data Factory- und Azure Synapse-Pipelines kopieren. Dieser Artikel baut auf dem Artikel zur Kopieraktivität auf, der eine allgemeine Übersicht über die Kopieraktivität enthält.

Unterstützte Funktionen

Dieser SharePoint Online-Listenconnector wird für die folgenden Funktionen unterstützt:

Unterstützte Funktionen IR
Kopieraktivität (Quelle/-) ① ②
Lookup-Aktivität ① ②

① Azure Integration Runtime ② Selbstgehostete Integration Runtime

Eine Liste der Datenspeicher, die als Quellen oder Senken unterstützt werden, finden Sie in der Tabelle der unterstützten Datenspeicher.

Genauer gesagt, verwendet dieser SharePoint Online-Listenconnector die Dienstprinzipalauthentifizierung und ruft Daten über das OData-Protokoll ab.

Tipp

Dieser Connector unterstützt das Kopieren von Daten aus einer SharePoint Online-Liste jedoch nicht aus einer Datei. Im Abschnitt Kopieren von Dateien aus SharePoint Online erfahren Sie, wie Sie eine Datei kopieren.

Erste Schritte

Sie können eines der folgenden Tools oder SDKs verwenden, um die Kopieraktivität mit einer Pipeline zu verwenden:

Erstellen eines verknüpften Diensts für eine SharePoint Online-Liste über die Benutzeroberfläche

Führen Sie die folgenden Schritte aus, um einen verknüpften Dienst für eine SharePoint Online-Liste über die Benutzeroberfläche im Azure-Portal zu erstellen.

  1. Navigieren Sie in Ihrem Azure Data Factory- oder Synapse-Arbeitsbereich zur Registerkarte „Verwalten“, wählen Sie „Verknüpfte Dienste“ aus, und klicken Sie auf „Neu“:

  2. Suchen Sie nach „SharePoint“, und wählen Sie den SharePoint Online-Listenconnector aus.

    Screenshot: Der SharePoint Online-Listenconnector.

  3. Konfigurieren Sie die Dienstdetails, testen Sie die Verbindung, und erstellen Sie den neuen verknüpften Dienst.

    Screenshot: Konfiguration des verknüpften Dienstes für eine SharePoint Online-Liste.

Details zur Connectorkonfiguration

In den folgenden Abschnitten finden Sie Details zu Eigenschaften, mit denen Sie spezifische Entitäten für den SharePoint Online-Listenconnector definieren können.

Eigenschaften des verknüpften Diensts

Folgende Eigenschaften werden für einen mit einer SharePoint Online-Liste verknüpften Dienst unterstützt:

Eigenschaft Beschreibung Erforderlich
type Die type-Eigenschaft muss auf SharePointOnlineList festgelegt werden. Ja
siteUrl Die URL der SharePoint Online-Site, z. B. https://contoso.sharepoint.com/sites/siteName. Ja
servicePrincipalId Die Anwendungs-ID (Client-ID) für die in Microsoft Entra ID registrierte Anwendung. Ja
servicePrincipalCredentialType Geben Sie die Art der Anmeldeinformationen für die Dienstprinzipalauthentifizierung an. Zulässige Werte sind ServicePrincipalCert und ServicePrincipalKey. No
Für ServicePrincipalCert
servicePrincipalEmbeddedCert Geben Sie das base64-codierte Zertifikat Ihrer in Microsoft Entra ID registrierten Anwendung an, und stellen Sie sicher, dass der Zertifikatsinhaltstyp PKCS #12 lautet. Markieren Sie dieses Feld als SecureString, um es sicher zu speichern, oder verweisen Sie auf ein in Azure Key Vault gespeichertes Geheimnis. Sie müssen die Berechtigungseinstellungen für diesen Artikel konfigurieren. No
servicePrincipalEmbeddedCertPassword Geben Sie das Kennwort Ihres Zertifikats an, falls Ihr Zertifikat mit einem Kennwort geschützt ist. Markieren Sie dieses Feld als SecureString, um es sicher zu speichern, oder verweisen Sie auf ein in Azure Key Vault gespeichertes Geheimnis. No
Für ServicePrincipalKey
servicePrincipalKey Der Schlüssel der Anwendung. Markieren Sie dieses Feld als SecureString, um es sicher zu speichern, oder verweisen Sie auf ein in Azure Key Vault gespeichertes Geheimnis. Weitere Informationen, einschließlich Berechtigungseinstellungen, finden Sie in diesem Abschnitt. No
tenantId Die ID des Mandanten, unter dem sich Ihre Anwendung befindet. Ja
connectVia Die Integration Runtime, die zum Herstellen einer Verbindung mit dem Datenspeicher verwendet werden soll. Wenn keine Option angegeben ist, wird die standardmäßige Azure Integration Runtime verwendet. Nein

Hinweis

Wenn Sie die Dienstprinzipalschlüssel-Authentifizierung verwenden, die auf Azure ACS (Zugriffssteuerungsdienste) basiert, empfehlen wir, die Dienstprinzipalzertifikat-Authentifizierung aufgrund des ACS-Einstellungsplans zu wechseln.

Beispiel 1: Verwenden der Dienstprinzipal-Schlüsselauthentifizierung

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType":  "ServicePrincipalKey",
            "servicePrincipalKey": {
                "type": "SecureString",
                "value": "<service principal key>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Beispiel 2: Verwenden der Dienstprinzipal-Zertifikatauthentifizierung

{
    "name": "SharePointOnlineList",
    "properties": {
        "type": "SharePointOnlineList",
        "typeProperties": {
            "siteUrl": "<site URL>",
            "servicePrincipalId": "<service principal id>",
            "servicePrincipalCredentialType": "ServicePrincipalCert",
            "servicePrincipalEmbeddedCert": { 
                "type": "SecureString", 
                "value": "<base64 encoded string of (.pfx) certificate data>"
            },
            "servicePrincipalEmbeddedCertPassword": { 
                "type": "SecureString", 
                "value": "<password of your certificate>"
            },
            "tenantId": "<tenant ID>"
        },
        "connectVia": {
            "referenceName": "<name of Integration Runtime>",
            "type": "IntegrationRuntimeReference"
        }
    }
}

Erteilen der Berechtigung für die Verwendung des Dienstprinzipalschlüssels

Der SharePoint Online-Listenconnector verwendet die Dienstprinzipalauthentifizierung zum Herstellen einer Verbindung mit SharePoint. Führen Sie die folgenden Schritte aus, um sie einzurichten:

  1. Registrieren einer Anwendung bei der Microsoft Identity Platform. Eine Anleitung finden Sie unter Schnellstart: Registrieren einer Anwendung bei Microsoft Identity Platform. Notieren Sie sich die folgenden Werte, die Sie zum Definieren des verknüpften Diensts verwenden können:

    • Anwendungs-ID
    • Anwendungsschlüssel
    • Mandanten-ID

  2. Erteilen Sie der SharePoint Online-Site Berechtigungen für Ihre registrierte Anwendung, indem Sie die Schritte unten ausführen. Dazu benötigen Sie eine Websiteadministratorrolle.

    1. Öffnen Sie Ihren SharePoint Online-Websitelink. Beispielsweise die URL im Format https://<your-site-url>/_layouts/15/appinv.aspx, wobei der Platzhalter <your-site-url> Ihre Website ist.

    2. Suchen Sie die von Ihnen registrierte Anwendungs-ID, füllen Sie die leeren Felder aus, und klicken Sie auf „Erstellen“.

      • App-Domäne: contoso.com

      • Umleitungs-URL: https://www.contoso.com

      • XML-Code zur Berechtigungsanforderung:

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

        Erteilen der SharePoint Online-Website-Berechtigungen für Ihre registrierte Anwendung, wenn Sie die Rolle des Websiteadministrators haben.

      Hinweis

      Im Kontext des Konfigurierens des SharePoint-Connectors verweisen die „App-Domäne“ und „Umleitungs-URL“ auf die SharePoint-App, die Sie in Microsoft Entra ID registriert haben, um den Zugriff auf Ihre SharePoint-Daten zu gestatten. Die „App-Domäne“ ist die Domäne, in der Ihre SharePoint-Website gehostet wird. Wenn sich Ihre SharePoint-Website beispielsweise auf „https://contoso.sharepoint.com" befindet, handelt es sich bei der „App-Domäne“ um „contoso.sharepoint.com“. Die „Umleitungs-URL“ ist die URL, an die die SharePoint-App weiterleitet, nachdem sich der Benutzer authentifiziert und Berechtigungen für die App erteilt hat. Diese URL sollte eine Seite auf Ihrer SharePoint-Website sein, auf die die App zugreifen darf. Sie können beispielsweise die URL einer Seite verwenden, die eine Liste von Dateien in einer Bibliothek anzeigt, oder eine Seite, die den Inhalt eines Dokuments anzeigt.

    3. Klicken Sie für diese App auf „Vertrauen“.

Dataset-Eigenschaften

Eine vollständige Liste mit den Abschnitten und Eigenschaften, die zum Definieren von Datasets zur Verfügung stehen, finden Sie unter Datasets und verknüpfte Dienste. Der folgende Abschnitt enthält eine Liste der Eigenschaften, die vom SAP-Tabellen-Dataset unterstützt werden.

Eigenschaft Beschreibung Erforderlich
type Die type-Eigenschaft des Datasets muss auf SharePointOnlineLResource festgelegt sein. Ja
listName Der Name der SharePoint Online-Liste. Beachten Sie, dass das Hochkomma (') in Dateinamen nicht erlaubt ist. Ja

Beispiel

{
    "name": "SharePointOnlineListDataset",
    "properties":
    {
        "type": "SharePointOnlineListResource",
        "linkedServiceName": {
            "referenceName": "<SharePoint Online List linked service name>",
            "type": "LinkedServiceReference"
        },
        "typeProperties":
        {
            "listName": "<name of the list>"
        }
    }
}

Eigenschaften der Kopieraktivität

Eine vollständige Liste mit den verfügbaren Abschnitten und Eigenschaften zum Definieren von Aktivitäten finden Sie unter Pipelines. Der folgende Abschnitt enthält eine Liste der Eigenschaften, die von der SharePoint Online-Listenquelle unterstützt werden.

SharePoint Online-Liste als Quelle

Für das Kopieren von Daten aus SharePoint Online-Listen werden folgende Eigenschaften im Abschnitt source der Kopieraktivität unterstützt:

Eigenschaft Beschreibung Erforderlich
type Die type-Eigenschaft der Quelle der Kopieraktivität muss auf SharePointOnlineListSource festgelegt werden. Ja
Abfrage Benutzerdefinierte OData-Abfrageoptionen zum Filtern von Daten. Beispiel: "$top=10&$select=Title,Number". Nein
httpRequestTimeout Das Timeout (in Sekunden) für das Empfangen einer Antwort auf die HTTP-Anforderung. Die Standardeinstellung ist 300 (5 Minuten). Nein

Beispiel

"activities":[
    {
        "name": "CopyFromSharePointOnlineList",
        "type": "Copy",
        "inputs": [
            {
                "referenceName": "<SharePoint Online List input dataset name>",
                "type": "DatasetReference"
            }
        ],
        "outputs": [
            {
                "referenceName": "<output dataset name>",
                "type": "DatasetReference"
            }
        ],
        "typeProperties": {
            "source": {
                "type": "SharePointOnlineListSource",
                "query": "<OData query e.g. $top=10&$select=Title,Number>"
            }, 
            "sink": {
                "type": "<sink type>"
            }
        }
    }
]

Hinweis

Sie können für eine SharePoint Online-Listenquelle nicht mehrere choice-Datentypen auswählen.

Datentypzuordnung für SharePoint Online-Listen

Beim Kopieren von Daten aus SharePoint Online-Listen werden die folgenden Zuordnungen zwischen SharePoint Online-Listendatentypen und vom Dienst intern genutzten Zwischendatentypen verwendet.

SharePoint Online-Datentyp OData-Datentyp Zwischendatentyp
Einzelne Textzeile Edm.String String
Mehrere Textzeilen Edm.String String
Auswahl (Menü zum Auswählen) Edm.String String
Zahl (1, 1,0, 100) Edm.Double Double
Währung ($, ¥, €) Edm.Double Double
Datum und Uhrzeit Edm.DateTime Datetime
Suche (Informationen auf dieser Site) Edm.Int32 Int32
Ja/nein (Kontrollkästchen) Edm.Boolean Boolean
Person oder Gruppe Edm.Int32 Int32
Hyperlink oder Bild Edm.String String
Berechnet (Berechnung basierend auf anderen Spalten) Edm.String/Edm.Double/Edm.DateTime/Edm.Boolean String/Double/DateTime/Boolean
Attachment Nicht unterstützt
Aufgabenergebnis Nicht unterstützt
Externe Daten Nicht unterstützt
Verwaltete Metadaten Nicht unterstützt

Kopieren von Dateien aus SharePoint Online

Sie können eine Datei aus SharePoint Online kopieren, indem Sie mit einer Webaktivität das Zugriffstoken von SPO authentifizieren und erfassen und dann an eine nachfolgende Kopieraktivität übergeben, um Daten mit einem HTTP-Connector als Quelle zu kopieren.

SharePoint-Kopierdateiflow

  1. Folgen Sie der Berechtigung zum Erteilen der Verwendung des Dienstprinzipalschlüsselabschnitts, um eine Microsoft Entra-Anwendung zu erstellen und SharePoint Online Berechtigungen zu erteilen.

  2. Erstellen Sie eine Webaktivität, um das Zugriffstoken aus SharePoint Online zu erhalten:

    • URL:https://accounts.accesscontrol.windows.net/[Tenant-ID]/tokens/OAuth/2. Ersetzen Sie die Mandanten-ID.
    • Methode: POST
    • Headers:
      • Content-Type: application/x-www-form-urlencoded
    • Text:grant_type=client_credentials&client_id=[Client-ID]@[Tenant-ID]&client_secret=[Client-Secret]&resource=00000003-0000-0ff1-ce00-000000000000/[Tenant-Name].sharepoint.com@[Tenant-ID]. Ersetzen Sie die Client-ID (Anwendungs-ID), den geheimen Clientschlüssel (Anwendungsschlüssel), die Mandanten-ID und den Namen des Mandanten (des SharePoint-Mandanten).

    Achtung

    Legen Sie die Option „Secure Output“ (Sichere Ausgabe) in der Webaktivität auf TRUE fest, um zu verhindern, dass der Tokenwert als Klartext protokolliert wird. Für alle weiteren Aktivitäten, die diesen Wert verwenden, sollte die Option „Sichere Eingabe“ auf „True“ festgelegt werden.

  3. Kette mit einer Kopieraktivität mit HTTP-Connector als Quelle zum Kopieren von SharePoint Online-Dateiinhalten:

    • Verknüpfter HTTP-Dienst:
      • Basis-URL:https://[site-url]/_api/web/GetFileByServerRelativeUrl('[relative-path-to-file]')/$value. Ersetzen Sie die Site-URL und den relativen Pfad zur Datei. Achten Sie darauf, dass Sie die URL der SharePoint-Website zusammen mit dem Domänennamen angeben, z. B. https://[sharepoint-domain-name].sharepoint.com/sites/[sharepoint-site]/_api/web/GetFileByServerRelativeUrl('/sites/[sharepoint-site]/[relative-path-to-file]')/$value.
      • Authentifizierungstyp: Anonym (zum Verwenden des später in der Quelle der Kopieraktivität konfigurierten Bearertokens)
    • Dataset: Wählen Sie das gewünschte Format aus. Um die Datei unverändert zu kopieren, wählen Sie den Typ „Binär“ aus.
    • Quelle der Kopieraktivität:
      • Anforderungsmethode: GET
      • Zusätzliche Header: Verwenden Sie den Ausdruck @{concat('Authorization: Bearer ', activity('<Web-activity-name>').output.access_token)}, der das von der Upstreamwebaktivität generierte Bearertoken als Autorisierungsheader verwendet. Ersetzen Sie den Namen der Webaktivität.
    • Konfigurieren Sie die Kopieraktivitätssenke für jedes unterstützte Senkenziel.

Hinweis

Auch wenn eine Microsoft Entra-Anwendung über FullControl-Berechtigungen für SharePoint Online verfügt, können Sie keine Dateien aus Dokumentbibliotheken mit aktiviertem IRM kopieren.

Eigenschaften der Lookup-Aktivität

Ausführliche Informationen zu den Eigenschaften finden Sie unter Lookup-Aktivität.

Zugehöriger Inhalt

Eine Liste der Datenspeicher, die die Kopieraktivität als Quellen und Senken unterstützt, finden Sie unter Unterstützte Datenspeicher und Formate.