Freigeben über

Lernprogramm: Ausführen einer Fabric-Datenpipeline und eines Notizbuchs mit Apache Airflow-DAGs

Hinweis

Ein Apache Airflow-Auftrag wird von Apache Airflow unterstützt.

In diesem Tutorial erstellen Sie einen gerichteten azyklischen Graph, um ein Microsoft Fabric-Element auszuführen, wie Pipelines und Notebooks.

Voraussetzungen

Um zu beginnen, müssen die folgenden Voraussetzungen erfüllt sein:

Hinweis

Stellen Sie sicher, dass der Apache Airflow-Auftrag in der Kapazitätsregion verfügbar ist, die Sie für Ihren Arbeitsbereich verwenden. Weitere Informationen finden Sie in den verfügbaren Kapazitätsregionen.

  • Erstellen Sie eine Microsoft Entra ID-App, wenn Sie keine haben.

  • Im Administratorkonto auf Mandantenebene muss die Einstellung „Benutzereinwilligung für Apps zulassen“ aktiviert werden. So konfigurieren Sie Einstellungen für die Benutzereinwilligung über das Microsoft Entra Admin Center:

    1. Melden Sie sich beim Microsoft Entra Admin Center mit der Rolle Administrator für privilegierte Rollen an.

    2. Navigieren Sie zu den Einstellungen unter Identität>Anwendungen>Unternehmensanwendungen>Zustimmung und Berechtigungen>Benutzerzustimmung.

    3. Wählen Sie unter Benutzereinwilligung für Anwendungen aus, welche Einwilligungseinstellung für alle Benutzer konfiguriert werden soll.

    4. Klicken Sie auf Speichern, um Ihre Einstellungen zu speichern. Screenshot zum Aktivieren der Benutzereinwilligung im Mandanten.

    Weitere Informationen finden Sie unter: Konfigurieren der Benutzerzustimmung

  • Stellen Sie sicher, dass das Konto, das zum Generieren der Aktualisierungstoken verwendet wird, über Mitwirkendeberechtigungen für den Arbeitsbereich verfügt, der die Datenpipeline und das Notizbuch enthält.

  • Aktivieren Sie die Trigger in Datenworkflows, um die Verwendung von zurückgestellten Operatoren zu ermöglichen. Screenshot zum Aktivieren von Triggern.

Plug-In für Apache Airflow

Um eine On-Demand-Ausführung eines Microsoft Fabric-Elements auszulösen, verwendet dieses Lernprogramm das apache-airflow-microsoft-fabric-plugin, das in den Anforderungen der Apache Airflow-Jobs vorinstalliert ist.

Authentifizierung

Um Microsoft Fabric-APIs aufzurufen, muss eine App ein Zugriffstoken von der Microsoft Identity Platform abrufen. Dieses Zugriffstoken enthält Informationen darüber, ob die App berechtigt ist, im Namen eines angemeldeten Benutzers oder mit eigener Identität auf Microsoft Fabric-Elemente zuzugreifen. Dieser Abschnitt enthält die unformatierten HTTP-Anforderungen, die für eine App erforderlich sind, um zugriff im Namen eines Benutzers mithilfe eines beliebten Flusses namens OAuth 2.0-Autorisierungscodegenehmigungsfluss zu erhalten.

Sie müssen die folgenden Schritte ausführen, um das Aktualisierungstoken abzurufen, das später in Apache Airflow-Verbindung verwendet wird:

  1. Anfordern eines Autorisierungsschlüssels.
  2. Anfordern eines Zugriffs- und Aktualisierungstokens.

Bevor Sie mit den Schritten in diesem Artikel fortfahren, speichern Sie die folgenden Werte aus der App-Registrierung, die Sie anfänglich erstellt haben:

  • Client-ID: Ein eindeutiger Bezeichner Ihrer Anwendung, die von der Microsoft Identity Platform zugewiesen wurde.
  • Geheimer Clientschlüssel: (Optional) Ein Kennwort, das Ihre App für die Authentifizierung bei der Microsoft Identity Platform verwendet. Diese Eigenschaft ist für öffentliche Clients wie systemeigene, mobile und Einzelseitenanwendungen nicht erforderlich.
  • Mandanten-ID: Ein eindeutiger Bezeichner für Ihren Mandanten in der Microsoft Identity Platform.
  • Umleitungs-URI/URL: Endpunkte, an denen Ihre App Antworten von der Microsoft Identity Platform empfängt. In diesen Schritten erhalten Sie einen Autorisierungscode bei registrierter Umleitungs-URI.

Schritt 1: Anfordern der Autorisierung

Autorisierungsendpunkt

Der erste Schritt im Autorisierungscodefluss besteht darin, dass der Benutzer die App autorisiert, in ihrem Auftrag zu handeln. Durch Senden der "GET"-Anforderung an den Endpunkt "/autorisieren" signiert Microsoft Entra-ID den Benutzer und fordert seine Zustimmung für die Berechtigungen an, die die App anfordert. Ersetzen Sie die Platzhalter durch Ihre Werte, und fügen Sie die folgende URL in Ihren Browser ein.

Das Plug-In erfordert die folgenden Authentifizierungsbereiche:

  • itemType.Execute.All (z. B. Notebook.Execute.All, Pipeline.Execute.All): Das Aufrufen der Anwendung darf alle Artefakte von <Itemtype> ausführen, auf die der Benutzer Zugriff hat.
  • itemType.Read.All (z. B. Notebook.Execute.All, Pipeline.Execute.All): Das Aufrufen der Anwendung kann alle Artefakte vom Typ <itemType> lesen, auf die die benutzende Person zugreifen kann.
  • offline_access: Standardmäßiger OIDC-Bereich angefordert, damit die App ein Aktualisierungstoken abrufen kann. Die App kann das Aktualisierungstoken verwenden, um ein neues Zugriffstoken abzurufen, wenn das aktuelle abläuft.
// Line breaks for legibility only
// This request uses Item.Execute.All, Item.Read.All and offline_access scopes. You can update them as per your requirements.


https://login.microsoftonline.com/{tenant}/oauth2/v2.0/authorize?
client_id={client_id}
&response_type=code
&redirect_uri={redirect_uri}
&response_mode=query
&scope=https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Execute.All%20https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Read.All%20offline_access 
&state=12345
&code_challenge=YTFjNjI1OWYzMzA3MTI4ZDY2Njg5M2RkNmVjNDE5YmEyZGRhOGYyM2IzNjdmZWFhMTQ1ODg3NDcxY2Nl
&code_challenge_method=S256

Weitere Informationen zu Parametern finden Sie im Anforderungsautorisierungscode.

Nachdem die App die Autorisierungsanforderung gesendet hat, wird der Benutzer aufgefordert, seine Anmeldeinformationen zur Authentifizierung bei Microsoft einzugeben. Der Microsoft Identity Platform v2.0-Endpunkt stellt sicher, dass der Benutzer den im Bereichsabfrageparameter angegebenen Berechtigungen zustimmt. Der folgende Screenshot ist ein Beispiel für das Zustimmungsdialogfeld, das für einen Microsoft-Kontobenutzer angezeigt wird.

Screenshot zum Anzeigen der Benutzerzustimmung während der Authentifizierung mit Microsoft Fabric.

Autorisierungsantwort

Wenn der Benutzer den von der App angeforderten Berechtigungen zustimmt, sendet die Microsoft Identity Platform einen Autorisierungscode an den Umleitungs-URI der App. Hier ist ein Beispiel für eine erfolgreiche Antwort auf die vorherige Anforderung. Da der Parameter „response_mode“ in der Anforderung auf Abfrage festgelegt wurde, wird die Antwort in der Abfragezeichenfolge der Umleitungs-URL zurückgegeben. Kopieren Sie für den nächsten Schritt den Wert "Code" aus der Antwort.

HTTP/1.1 200 OK

https://localhost/myapp/?
code=M0ab92efe-b6fd-df08-87dc-2c6500a7f84d...
&state=12345
&session_state=fe1540c3-a69a-469a-9fa3-8a2470936421#

Schritt 2: Anfordern eines Zugriffstokens

Die App verwendet den im vorherigen Schritt empfangenen Autorisierungscode, um ein Zugriffstoken anzufordern, indem eine POST-Anforderung an den /token-Endpunkt gesendet wird. Stellen Sie sicher, dass Ihr Bereich und redirect_uri den Werten entsprechen, die Sie im vorherigen Schritt verwendet haben. Sie können die folgende Anfrage in ein Tool wie Insomnia einfügen, um die Anfrage zu senden.

// Line breaks for legibility only
// This request uses Item.Execute.All, Item.Read.All and offline_access scopes. You can update them as per your requirements.

POST /{tenant}/oauth2/v2.0/token HTTP/1.1
Host: https://login.microsoftonline.com
Content-Type: application/x-www-form-urlencoded

client_id={client_id}
&scope=https%3A%2F%2Fapi.fabric.microsoft.com%2FItem.Execute.All%2FItem.Read.All%20offline_access
&code=OAAABAAAAiL9Kn2Z27UubvWFPbm0gLWQJVzCTE9UkP3pSx1aXxUjq3n8b2JRLk4OxVXr...
&redirect_uri={redirect_uri}
&grant_type=authorization_code
&code_verifier=WuiPvLwjYU6ehi--Gv5P58u7NOd4dJgE8BSQzZ-7nT3xq4OrVp2cxADyUvYJqkH2sfLhPjuqUCbbbk4x11cfzLCKADIE8mht3vwyGoSL7DnMhC4SFAunOx_mJ99hVeKh
&client_secret={client_secret}   // NOTE: (Optional) Only required for web apps.

Weitere Informationen zu Parametern finden Sie unter Anfordern eines Zugriffstokens.

Zugriffstokenantwort

Das Zugriffstoken enthält eine Liste der Berechtigungen, für die das Zugriffstoken im Bereichsparameter geeignet ist. Die Antwort ähnelt dem folgenden Beispiel. Kopieren Sie den Wert "refresh_token" aus der Antwort für die Verwendung in der Apache Airflow-Verbindung.

HTTP/1.1 200 OK
Content-type: application/json

{
    "token_type": "Bearer",
    "scope": "Mail.Read User.Read",
    "expires_in": 3736,
    "ext_expires_in": 3736,
    "access_token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Ik5HVEZ2ZEstZnl0aEV1Q...",
    "refresh_token": "AwABAAAAvPM1KaPlrEqdFSBzjqfTGAMxZGUTdM0t4B4..."
}

Einrichten der Apache Airflow-Verbindung

Die Apache Airflow-Verbindung wird verwendet, um die Anmeldeinformationen zu speichern, die für die Authentifizierung mit Microsoft Fabric-APIs erforderlich sind.

  1. Navigieren Sie zu "Airflow-Verbindungen anzeigen", um eine neue Apace Airflow-Verbindung hinzuzufügen. Screenshot zum Anzeigen der Apache Airflow-Verbindung.

  2. Fügen Sie eine neue Verbindung hinzu, und füllen Sie die folgenden Details aus:

    • Verbindungs-ID: Name der Verbindungs-ID.

    • Verbindungstyp: Generisch

    • Anmelden: Die Ihrer App zugewiesene Anwendungs-ID (Client-ID).

    • Kennwort: Das Aktualisierungstoken, das im vorherigen Schritt abgerufen wurde.

    • Extra: Dieses Feld enthält die folgenden Parameter:

      • tenantId: (Erforderlich) Mit dem {Tenant}-Wert im Pfad der Anforderung kann festgelegt werden, welche Benutzer*innen sich bei der Anwendung anmelden können.
      • clientSecret: (Optional, nur erforderlich für Web-Apps) Der geheime Clientschlüssel der App-Registrierung.
      • Bereiche: (Erforderlich) Durch Leerzeichen getrennte Zeichenfolge von Bereichen, die für den Zugriff auf die Microsoft Fabric-APIs für die App erforderlich sind.

      Kopieren Sie das folgende JSON-Objektformat, aktualisieren Sie die Werte, entfernen Sie den Kommentar, und fügen Sie ihn in das Feld "Extra" ein.

      {
    "tenantId": "{tenant}",
    "scopes": "https://api.fabric.microsoft.com/Item.Execute.All https://api.fabric.microsoft.com/Item.Read.All offline_access",
    "clientSecret": "{client-secret}" // (Optional) NOTE: Only required for web apps.
}

      Screenshot zum Festlegen der Apache Airflow-Verbindung für Microsoft Fabric.

  3. Wählen Sie Speichern.

Erstellen Sie eine DAG zum Auslösen von Microsoft Fabric-Element Ausführungen

Erstellen Sie eine neue DAG-Datei mit folgendem Code im Ordner „dags“ im Fabric-verwalteten Speicher. Ersetzen Sie die folgenden Platzhalter:

  • fabric_conn_id: Die Verbindungs-ID, die Sie im vorherigen Schritt erstellt haben.
  • workspace_id: Die Arbeitsbereichs-ID, in der sich das Element befindet.
  • item_id: Die Element-ID des Elements, das Sie ausführen möchten. Beispielsweise eine Notebook-ID oder eine Pipeline-ID.
  • job_type: Der Typ des Elements, das Sie ausführen möchten. Verwenden Sie beispielsweise für Notebooks „RunNotebook“, für Spark Job Definitions „sparkjob“ und für Pipelines „Pipeline“. Hierbei muss die Groß-/Kleinschreibung beachtet werden.
  • wait_for_termination: Wenn dieser Wert auf "True" festgelegt ist, wartet der Operator, bis das Element ausgeführt wird, bevor er mit der nächsten Aufgabe fortschreitet.
  • deferrable: Bei Festlegung auf "True" kann der Operator Ressourcen freigeben, während auf die Ausführung des Elements gewartet wird.
from airflow import DAG
from datetime import datetime
from apache_airflow_microsoft_fabric_plugin.operators.fabric import FabricRunItemOperator

with DAG(
  dag_id="Run_Fabric_Item",
  schedule_interval="@daily",
  start_date=datetime(2023, 8, 7),
  catchup=False,
) as dag:

  run_fabric_item = FabricRunItemOperator(
    task_id="run_fabric_item",
    fabric_conn_id="fabric_conn",
    workspace_id="<workspace_id>",
    item_id="<item_id>",
    job_type="<job_type>",
    wait_for_termination=True,
    deferrable=True,
  )

  run_fabric_item

Erstellen einer Plug-In-Datei für den benutzerdefinierten Operator

Wenn Sie einen externen Überwachungslink für die Ausführung eines Microsoft Fabric-Artikels einschließen möchten, erstellen Sie eine Plug-In-Datei wie folgt:

Erstellen Sie eine neue Datei mit folgendem Code im plugins-Ordner:

   from airflow.plugins_manager import AirflowPlugin

   from apache_airflow_microsoft_fabric_plugin.hooks.fabric import FabricHook
   from apache_airflow_microsoft_fabric_plugin.operators.fabric import FabricRunItemLink

   class AirflowFabricPlugin(AirflowPlugin):
      """
      Microsoft Fabric plugin.
      """

      name = "fabric_plugin"
      operator_extra_links = [FabricRunItemLink()]
      hooks = [
          FabricHook,
      ]

Überwachen Sie Ihre DAG

In der Benutzeroberfläche des Apache Airflow-Auftrags

  1. Wenn Sie Ihre DAG-Datei im verwalteten Speicher in Fabric öffnen, wird unten „Ergebnisse“ angezeigt. Wählen Sie den Pfeil aus, um die Ergebnisse der DAG-Ausführung anzuzeigen. Screenshot zum Anzeigen der DAG-Datei in Apache Airflow im Apache Airflow-Auftrag.

In der Benutzeroberfläche von Apache Airflow

  1. Wechseln Sie zur Airflow-Benutzeroberfläche, und wählen Sie die von Ihnen erstellte DAG aus.

  2. Wenn Sie das Plug-In hinzufügen, wird ein Link zur externen Überwachung angezeigt. Wählen Sie die Option aus, um zur Ausführung des Elements zu navigieren. Screenshot zum Anzeigen von Apache Airflow DAGs mit externem Link.

  3. Xcom-Integration: Lösen Sie die DAG aus, um die Aufgabenausgaben auf der Registerkarte Xcom anzuzeigen. Screenshot zum Anzeigen von Apache Airflow DAGs mit der Registerkarte Xcom.

Verwandte Inhalte

Schnellstart: Erstellen eines Apache Airflow-AuftragsEinstellungen im Arbeitsbereich des Apache Airflow-Auftrags