Erstellen einer anpassbaren externen Funktion auf Azure

In diesem Dokument wird eine Möglichkeit zum Erstellen einer externen Funktion auf Microsoft Azure gezeigt.

Diese Anleitung setzt voraus, dass Sie bereits mit der Administration von Microsoft Azure vertraut sind. In dieser Anleitung werden die allgemeinen Schritte beschrieben, die Sie ausführen müssen, aber nicht die Azure Portal-Benutzeroberfläche im Detail, da sich die Details ändern könnten.

Unter diesem Thema:

Voraussetzungen

Sie benötigen:

  • Einen Azure AD (Active Directory)-Mandanten

  • Ein Konto bei diesem Azure AD-Mandanten. Das Konto muss über folgende Berechtigungen verfügen:

    • Erstellen einer Azure-Funktionen-App

    • Erstellen eines Azure API Management-Dienstendpunkts

    • Registrieren einer Azure AD-Anwendung

  • Wenn Sie planen, eine Azure-Funktion auf Linux als Remotedienst zu verwenden, müssen Sie eine gültige Kombination aus Authentifizierung und Azure-Tarife wählen:

    • Wenn Sie den Premium- oder App Service-Tarif verwenden, können Sie die Azure AD-Anwendung auf der Azure-Registerkarte Authentication/Authorization erstellen und Azure AD zur Authentifizierung mit dem Azure-Funktionsdienst verwenden.

    • Wenn Sie den „Consumption“-Tarif verwenden, gehen Sie wie folgt vor:

Vorbereiten des Erstellens einer externen Funktion auf Azure

Die folgenden Informationen sollten bereits vorliegen:

Azure AD Tenant ID: _____________________________________

    This is a UUID.

Wenn Sie Ihren Azure AD-Mandanten-ID noch nicht kennen, können Sie diese wie folgt ermitteln:

  1. Melden Sie sich beim Azure-Portal (http://portal.azure.com) an.

  2. Klicken Sie oben auf der Seite unter den „Azure Services“-Symbolen auf „Azure Active Directory“.

  3. Suchen Sie im Menü auf der linken Seite nach dem Abschnitt mit dem Titel Manage, und klicken Sie darunter auf Properties.

    Die Azure AD-Mandanten-ID wird im Feld „Tenant ID“ (Mandanten-ID) angezeigt.

Wenn Sie Ihre externe Funktion erstellen, sollten Sie sich bestimmte Informationen, die Sie eingeben, notieren (z. B. den Namen der Azure-Funktionen-App), damit Sie diese Informationen in nachfolgenden Schritten verwenden können. Das Arbeitsblatt unten hilft Ihnen, diese Informationen festzuhalten.

==============================================================================================
=========================================== Worksheet ========================================
==============================================================================================

----------------- Information about the Azure Function (remote service) ----------------------

Azure Function app name................: _________________________________________

HTTP-Triggered Function name...........: _________________________________________

Azure Function AD app registration name: _________________________________________

Azure Function AD Application ID.......: _________________________________________

    (This is the "Application (client) ID" of the Azure AD app registration for the Azure function, and
    is used to fill in the "azure_ad_application_id" field in the CREATE API INTEGRATION command.
    This is in the form of a UUID. See https://en.wikipedia.org/wiki/Universally_unique_identifier .)


------------ Information about the Azure API Management Service (proxy service) --------------

API Management service name......: __________________________________________

API Management API URL suffix....: __________________________________________


---------------- Snowflake API Integration and External Function Information -----------------

API Integration Name.............: _______________________________________________

AZURE_MULTI_TENANT_APP_NAME......: _______________________________________________

AZURE_CONSENT_URL................: _______________________________________________

External Function Name...........: _______________________________________________

External Function Name.....: _______________________________________________

Schritt 1: Remotedienst erstellen (Azure-Funktion)

In diesem Tutorial wird ein Remotedienst als Azure-Funktion implementiert.

Azure-Funktionen-App erstellen

Der erste Schritt besteht darin, eine Azure-Funktionen-App zu erstellen, die als Container für die Funktion(en) dient, die Sie später erstellen.

Sie können die Funktionen-App erstellen, indem Sie die Anleitung von Microsoft verwenden (ein Link zu dieser Anleitung finden Sie unten). Wenn Sie diese Anleitung verwenden, denken Sie an Folgendes:

  • Wenn Sie einen Namen in das Feld „Function App Name“ (Name der Funktionen-App) eingeben, notieren Sie sich diesen Namen auch im Feld „Azure function app name“ auf dem obigen Arbeitsblatt ein.

  • Für das Erstellen mehrerer Apps in derselben Ressourcengruppe gelten einige Einschränkungen. Weitere Details dazu finden Sie unter:

    https://docs.microsoft.com/en-us/azure/app-service/containers/app-service-linux-intro#limitations

  • Snowflake stellt eine „Echo“-Beispielfunktion in Node.js bereit. Wenn Sie diese Beispielfunktion zum Einstieg verwenden möchten, dann gehen Sie wie folgt vor:

Eine Anleitung von Microsoft zum Erstellen einer Azure-Funktionen-App finden Sie hier:

Über HTTP ausgelöste Funktion erstellen

Nachdem Sie Ihre Azure-Funktionen-App (Container) erstellt haben, müssen Sie eine Azure-Funktion in diesem Container erstellen. Diese Funktion fungiert als der Remotedienst.

Microsoft erlaubt das Aufrufen (Auslösen) von Azure-Funktionen auf unterschiedliche Weise. Eine externe Snowflake-Funktion ruft einen Remotedienst über einen HTTP-POST-Befehl auf, d. h. die von Ihnen erstellte Azure-Funktion muss eine „über HTTP ausgelöste Funktion“ sein.

Microsoft dokumentiert hier, wie eine über HTTP ausgelöste Funktion erstellt wird:

Die Anweisungen von Snowflake unten sind ähnlich, enthalten jedoch zusätzliche Details und Beispielcode und schlagen eine andere Autorisierungsstufe als Microsoft vor.

Bevor Sie die unten stehenden Anweisungen ausführen, sollten Sie sich auf dem Bildschirm „Function App“ befinden. Der Name Ihrer Azure-Funktionen-App sollte normalerweise in der linken oberen Ecke des Bildschirms angezeigt werden.

  1. Suchen Sie im Menüstrukturbaum auf der linken Seite nach dem Abschnitt mit dem Titel Functions. Klicken Sie in diesem Abschnitt auf das Element mit der Bezeichnung Functions, um eine Funktion hinzuzufügen.

  2. Klicken Sie auf die Schaltfläche + Add.

  3. Wählen Sie auf der rechten Seite in der Liste der potenziellen Trigger die Option HTTP trigger aus.

  4. Geben Sie den Namen ein, der für Ihre über HTTP ausgelöste Funktion verwendet werden soll.

    Zeichnen Sie diesen Namen im Feld „HTTP-Triggered Function name“ des Arbeitsblatts auf.

  5. Geben Sie den Authorization level ein.

    Snowflake empfiehlt, als Autorisierungsstufe Function auszuwählen.

    Weitere Informationen zu möglichen Autorisierungsstufen finden Sie unter: https://docs.microsoft.com/en-us/azure/azure-functions/functions-bindings-http-webhook-trigger?tabs=csharp#configuration

  6. Klicken Sie auf die Schaltfläche Add.

    Dadurch gelangen Sie zu einem Bildschirm, auf dem der Name der Funktion und darunter das Wort „Function“ angezeigt werden.

  7. Klicken Sie im Strukturbaum-Menü auf der linken Seite auf „Code + Test“.

  8. Ersetzen Sie den Standardcode durch Ihren eigenen Code.

    Hier ist ein Beispiel für eine JavaScript-„echo“-Funktion, die einfach die Zeilen zurückgibt, die an sie übergeben wurde.

    Die Funktion liest jede Zeile und kopiert diese Zeile dann in die Ausgabe (Ergebnisse). Die Zeilennummer ist ebenfalls in der Ausgabe enthalten. Die Ausgabe wird als Teil eines mehrstufigen Wörterbuchs zurückgegeben.

    Normalerweise gibt die Funktion den HTTP-Code 200 zurück. Wenn keine Zeilen an die Funktion übergeben werden (d. h. wenn der Anforderungstext leer ist), gibt die Funktion den Fehlercode 400 zurück.

    module.exports = async function(context, request) {
        context.log('JavaScript HTTP trigger function processed a request.');
    
        if (request.body) {
            var rows = request.body.data;
            var results = [];
            rows.forEach(row => {
                results.push([row[0], row]);
            });
    
            results = {data: results}
            context.res = {
                status: 200,
                body: JSON.stringify(results)
            };
       }
       else {
           context.res = {
               status: 400,
               body: "Please pass data in the request body."
           };
       }
    };
    
  9. Klicken Sie über dem Code auf die Schaltfläche Save.

  10. Sie können den Code Ihrer Azure-Funktion testen, indem Sie auf die Schaltfläche „Test/Run“ klicken.

    Für den Test benötigen Sie eine Nutzlast (Daten). Eine Beispielnutzlast finden Sie unten:

    {
         "data": [ [ 0, 43, "page" ], [ 1, 42, "life, the universe, and everything" ] ]
    }
    

    Der Inhalt der Ausgabe sollte in etwa wie folgt aussehen:

    { "data":
        [
            [ 0, [ 0, 43, "page" ] ],
            [ 1, [ 1, 42, "life, the universe, and everything" ]  ]
        ]
    }
    

Beachten Sie, dass die Formatierung von der oben gezeigten abweichen kann.

Autorisierungsanforderungen für die Azure-Funktionen-App festlegen

Wenn eine externe Funktion aufgerufen wird, sendet Snowflake einen HTTP-POST-Befehl an den Proxydienst (z. B. den Azure API Management-Dienst), der den POST-Befehl an den Remotedienst (z. B. die Azure-Funktion) weiterleitet.

Für jeden dieser beiden Schritte sollten Autorisierungsanforderungen gelten, sodass Sie in der Regel Folgendes angeben:

  • Die Autorisierung, die zum Aufrufen des API Management-Dienstes erforderlich ist.

  • Die Autorisierung, die zum Aufrufen von Funktionen der Azure-Funktionen-App, die Ihre Azure-Funktion enthält, erforderlich ist.

Der folgende Abschnitt beschreibt, wie Sie eine Autorisierung für Ihre Azure-Funktionen-App anfordern. (Der API Management-Dienst wird später erstellt, daher werden dessen Autorisierungsanforderungen ebenfalls später festgelegt).

Wenn Snowflake sich bei Ihrer Azure-Funktionen-App authentifiziert, verwendet Snowflake den Bereitstellungsablauf für OAuth-Clientanmeldinformationen für Azure AD.

(Weitere Einzelheiten zum Ablauf der Bereitstellung von Clientanmeldeinformationen finden Sie hier: https://docs.microsoft.com/en-us/azure/active-directory/azuread-dev/v1-oauth2-client-creds-grant-flow.)

Dieser Clientanmeldeinformationsablauf erfordert eine Azure AD-App-Registrierung, die die Azure-Funktionen-App repräsentiert.

Dieser Abschnitt enthält die Anweisungen zum Erstellen der Azure AD-App-Registrierung für die Azure-Funktionen-App. Beispielsweise können Sie Ihre Azure-Funktionen-App so einstellen, dass eine Azure AD-Authentifizierung erforderlich ist. Um die Autorisierung über Azure AD zu konfigurieren, müssen Sie Folgendes tun:

  • Erstellen Sie eine Azure AD-App-Registrierung, bei der es sich um eine Azure AD-basierte Entität handelt, die eine Identität oder einen Ressourcenbezeichner repräsentiert (d. h. das, was Sie schützen möchten).

  • Ordnen Sie die Azure AD-App-Registrierung der Azure-Funktionen-App zu, für die Sie eine Authentifizierung anfordern möchten.

Bemerkung

Für Azure-Funktionen besteht der schnellste Weg, eine Azure AD-App-Registrierung zu erstellen, in der Aktivierung von Azure AD Authentication für den Dienst, wie unten dokumentiert. Wenn Sie als Remotedienst keine Azure-Funktion verwenden möchten, verwenden Sie die Seite App-Registrierungen, um eine neue Azure AD-App-Registrierung für Ihren Remotedienst zu erstellen. Weitere Einzelheiten zur App-Registrierung finden Sie in folgender Microsoft-Dokumentation:

Bevor Sie die folgenden Schritte ausführen, sollten Sie sich auf dem Bildschirm „Funktionen-App“ Ihrer Azure-Funktionen-App befinden.

  1. Suchen Sie im linken Menüfenster den Abschnitt mit dem Namen Settings, und klicken Sie darunter auf Authentication / Authorization.

    Wenn am linken Rand das Menü „Developer“ angezeigt wird (mit „Code + Test“, „Integration“ usw.) und am unteren Bildschirmrand eine Bildlaufleiste angezeigt wird, versuchen Sie den Schieberegler nach links zu schieben, um zum Abschnitt Function App oder „App Service“ zurückzukehren, und suchen Sie dann nach Settings.

  2. Suchen Sie die Schaltfläche App Service Authentication, und ändern Sie den Wert von Off in On.

    Wenn Sie die Einstellungen auf dieser Seite Authentication / Authorization nicht ändern können, lesen Sie den folgenden Tipp zur Problembehandlung: Einstellungen für die Azure-Funktion unter dem Menüpunkt Authentication/Authorization können nicht geändert werden.

  3. Suchen Sie das Dropdown-Menü „Action to take when request is not authenticated“, und wählen Sie den Wert „Log in with Azure Active Directory“ aus.

  4. Wählen Sie unter „Authentication Providers“ die Option „Azure Active Directory“ aus.

Fahren Sie mit dem nächsten Abschnitt fort, um die Authentifizierung über Azure Active Directory (AD) zu konfigurieren.

Authentifizierung über Azure Active Directory

An diesem Punkt sollten Sie sich auf dem Bildschirm „Azure Active Directory Settings“ befinden.

  1. Ändern Sie die Schaltfläche Management mode von Off in entweder Express oder Advanced. (Die folgenden Anweisungen gehen davon aus, dass Sie Express gewählt haben).

  2. Um die Azure AD-App-Registrierung für Ihre Azure-Funktionen-App zu erstellen, führen Sie die folgenden Schritte aus:

    1. Suchen Sie Management mode, und wählen Sie entweder Create New AD App oder Select Existing AD App aus.

      Wählen Sie für diese Demonstration Create New AD App aus, es sei denn, Sie haben bereits eine Azure AD-App-Registrierung, die Sie verwenden möchten.

    2. Standardmäßig ist der Registrierungsname der Azure AD-App derselbe wie der Name der Azure-Funktionen-App. Dieser Name sollte im Feld „Create App“ angezeigt werden. Sie können diesen Namen bei Bedarf ändern.

      Notieren Sie sich den Registrierungsnamen der Azure AD-App im Feld „Azure function AD app registration name“ des Arbeitsblatts.

    3. Klicken Sie unten links im Fenster auf die Schaltfläche OK. Dadurch wird eine Azure AD-App-Registrierung erstellt, und Sie kehren zum Bildschirm „App Service Authentication/Authorization“ zurück.

    4. Überprüfen Sie, ob die Schaltfläche mit dem Namen App Service Authentication auf On steht.

    5. Klicken Sie auf die Schaltfläche Save, die sich in der linken oberen Ecke des Hauptbereichs (rechts neben dem Menübereich) befindet.

    Die meisten der oben beschriebenen Schritte sind auch in der Azure-Dokumentation aufgeführt, der Sie aber noch weitere Details entnehmen können:

Ihre Azure AD-App ist nun registriert. Im nächsten Schritt wird überprüft, ob die App unter „App registrations“ aufgeführt wird.

  1. Öffnen Sie eine neue Browser-Registerkarte, gehen Sie zu http://portal.azure.com, und klicken Sie dann auf App Registrations.

    Wenn dies nicht sichtbar ist, dann suchen Sie im Microsoft Azure-Suchfenster am oberen Rand des Bildschirms „App Registration“.

    Sie sollten sich jetzt auf dem Bildschirm „App registrations“ befinden.

    Sie sollten zwei Registerkarten sehen, eine mit dem Titel „All applications“ und eine mit dem Titel „Owned applications“.

  2. Wählen Sie die Registerkarte „All applications“ aus, falls diese nicht bereits ausgewählt ist.

  3. Klicken Sie auf den Namen der Azure AD-App-Registrierung, die Sie gerade für Ihre Azure-Funktionen-App erstellt haben.

    Bemerkung

    Sie können die Suchleiste verwenden, um Ihre Azure AD-App nach Namen zu suchen. Geben Sie dazu die ersten Zeichen des Namens ein. Die Suchfunktion geht davon aus, dass Sie den führenden Teil des Namens eingeben, und sucht daher die angegebene Teilzeichenfolge nicht im gesamten Funktionsnamen.

    Dies sollte Sie zum Bildschirm „App registrations“ führen.

  4. Auf dem App-Registrierungsbildschirm, der die Azure AD-App Ihrer Azure-Funktionen-App beschreibt, sollten der Name Ihrer Azure AD-App angezeigt werden.

  5. Suchen Sie das Feld „Application (client) ID“.

    Notieren Sie sich den Namen im Feld „Azure Function AD Application ID“ des Arbeitsblatts. (Stellen Sie sicher, dass Sie die ID und nicht den Azure AD-Anwendungsnamen kopieren. Die ID sollte ein UUID enthalten).

Schritt 2: Proxydienst (Azure API Management-Dienst) erstellen und konfigurieren

Snowflake sendet keine Daten (HTTP-POST-Anforderungen) direkt an den Remotedienst (z. B. Azure-Funktion). Stattdessen sendet Snowflake die Daten an einen Proxydienst, der die Daten von Snowflake an den Remotedienst und vom Remotedienst zurück an Snowflake leitet.

Externe Snowflake-Funktionen auf Azure unterstützen Azure API Management als Proxydienst.

API Management-Dienst erstellen

Um den API Management-Dienst zu erstellen, befolgen Sie die Anleitung von Microsoft (ein Link zu der Anleitung befindet sich unten).

Wenn Sie diese Anweisungen ausführen, denken Sie daran, Folgendes zu tun:

  • Notieren Sie sich im obigen Arbeitsblatt unter „API Management service name“ den Namen des API Management-Dienstes (möglicherweise unter dem Titel Resource name zu finden).

Eine Anleitung von Microsoft zum Erstellen eines API Management-Dienstes finden Sie hier:

Das Bereitstellen des API Management-Dienstes kann 30 Minuten oder mehr dauern. Wenn die Bereitstellung abgeschlossen ist, sollten eine Meldung ähnlich der Meldung „Your deployment is complete“ angezeigt werden.

Nachdem die Bereitstellung abgeschlossen ist, klicken Sie auf die Schaltfläche Go to resource.

API, die die Azure-Funktion enthält, importieren

Nach dem Erstellen des API Management-Dienstes (Proxydienst) erfolgt der Import und die Veröffentlichung der Azure-Funktionen-App, die die APIs (Funktionen) enthält, über die dieser API Management-Dienst aufgerufen werden soll.

  1. Folgen Sie der Anleitung von Microsoft für den Import und die Veröffentlichung einer Azure-Funktion (ein Link zu der Anleitung befindet sich unten).

    Wenn Sie diese Anweisungen ausführen, denken Sie an Folgendes:

    • Einer dieser Schritte erfordert, dass Sie eine Option für Product angeben. Wählen Sie für diese Demonstration Starter anstelle von Unlimited aus. (Bei einem Produktionssystem können Sie auch eine andere Option auswählen).

    • Notieren Sie sich die folgenden Werte auf dem Arbeitsblatt:

      • Notieren Sie sich das API URL suffix im obigen Arbeitsblatt unter „API Management API URL suffix“.

    Unten finden Sie einen Link zu der von Microsoft bereitgestellten Anleitung. Diese Seite enthält Anweisungen für andere Aufgaben sowie für den Import von APIs. Für diese Demo benötigen Sie normalerweise nur die Anweisungen zum Importieren einer Azure-Funktionen-App als neue API.

    Nachdem Sie die in der Azure-Dokumentation aufgeführten Schritte zum Importieren einer Azure-Funktionen-App ausgeführt haben, sollten Sie sich wieder auf der Seite API Management service befinden.

  2. Wenn auf der Registerkarte Settings das Kontrollkästchen Subscription Required mit einem Häkchen versehen ist, entfernen Sie das Häkchen, es sei denn, Sie möchten ein Abonnement anfordern.

    (Wenn Sie den Abschnitt Subscription nicht sehen, scrollen Sie nach unten).

  3. Klicken Sie auf die Schaltfläche Save.

Bemerkung

Sie sollten Sicherheitsrichtlinien für den Azure API Management-Dienst festlegen. Sie können jetzt die Sicherheitsrichtlinie festlegen, oder Sie können zuerst die Erstellung der externen Funktion beenden und die Integritätsprüfung für die externe Funktion durchführen, bevor Sie die Sicherheitsrichtlinie für den Azure API Management-Dienst konfigurieren. Um das Debugging zu vereinfachen, werden bei dieser Anleitung zuerst die Erstellung und der Integritätstest der externen Funktion abgeschlossen.

Schritt 3: API-Integrationsobjekt in Snowflake erstellen

Voraussetzungen

Beachten Sie Folgendes:

CREATE API INTEGRATION-Anweisung zusammenstellen

  1. Öffnen Sie (falls noch nicht geschehen) eine Snowflake-Sitzung, normalerweise eine Snowflake-Weboberflächensitzung.

  2. Verwenden Sie eine Snowflake-Rolle mit ACCOUNTADMIN-Berechtigungen oder eine Rolle mit der Berechtigungen CREATE INTEGRATION, zum Beispiel:

    use role accountadmin;
    
  3. Geben Sie den Befehl CREATE API INTEGRATION ein, um eine API-Integration zu erstellen. Der Befehl sollte ungefähr wie folgt aussehen:

    create or replace api integration <integration_name>
        api_provider = azure_api_management
        azure_tenant_id = '<tenant_id>'
        azure_ad_application_id = '<azure_application_id>'
        api_allowed_prefixes = ('<url>')
        enabled = true;
    

    Integrationsname

    Dieser Name muss den Regeln für Objektbezeichner folgen.

    Mandanten-ID

    Die Azure AD-Mandanten-ID.

    Als Alternative können Sie Ihre Domäne verwenden (z. B. my_company.onmicrosoft.com).

    Azure-Anwendungs-ID

    Legen Sie hier als Wert die AD-Anwendungs-ID der Azure-Funktionen-App fest, die Sie auf dem Arbeitsblatt notiert haben.

    Erlaubte_API-Präfixe

    Dieses Feld erlaubt es Ihnen, die URLs einzuschränken, auf die diese API-Integration angewendet werden kann.

    Normalerweise enthält dieses Feld die URL des Proxydienstes (z. B. die URL des Azure API Management-Dienstes). Um dies weiter einzugrenzen, können Sie das API Management-API-URL-Suffix anhängen. Wenn Sie das API Management-API-URL-Suffix einfügen, dann sollte die URL im Feld api_allowed_prefixes in etwas wie folgt aussehen:

    https://<Name_des_API_Management-Dienstes>.azure-api.net/<API-URL-Suffix>

    Beispiel:

    Dies sollte mit der Basis-URL und dem Suffix auf der Registerkarte Settings Ihres API Management-Dienstes in Ihrer importierten API übereinstimmen. Sie können den Wert auch von dort kopieren.

    Weitere Details dazu finden Sie unter CREATE API INTEGRATION.

  4. Notieren Sie sich den Namen der erstellten API-Integration auf dem Arbeitsblatt unter „API-Integrationsname“. Sie benötigen den Namen der API-Integration, wenn Sie später den Befehl CREATE EXTERNAL FUNCTION ausführen.

  5. Führen Sie den oben eingegebenen CREATE API INTEGRATION-Befehl aus.

Schritt 5: Externe Funktion in Snowflake erstellen

Führen Sie in Snowflake den Befehl CREATE EXTERNAL FUNCTION aus. Der Befehl sieht ungefähr wie folgt aus:

create or replace external function <function_name>(<parameters>)
    returns variant
    api_integration = <api_integration_name>
    as '<invocation_URL>'
    ;

Funktionsname

Der Name der Funktion. Dieser Name muss den Regeln für Objektbezeichner folgen.

Parameter

Die Parameter der Funktion, falls vorhanden. Die Parameter sollten den Parametern des Remotedienstes entsprechen (z. B. Azure-Funktion). Die Parameternamen müssen nicht übereinstimmen, aber die Datentypen müssen kompatibel sein.

Wenn Ihre Azure-Funktion den oben angegebenen JavaScript-Beispielcode verwendet, dann sind die Parameter vom Typ INTEGER und VARCHAR.

API-Integrationsname

Der API-Integrationsname, den Sie sich zuvor auf dem Arbeitsblatt unter „API Integration Name“ notiert haben.

Aufruf_URL

Dies ist die URL, an die Snowflake den Befehl HTTP POST sendet, um den Remotedienst aufzurufen. Wenn der Proxydienst der Azure API Management-Dienst ist und der Remotedienst eine Azure-Funktion, dann sieht die URL ungefähr wie folgt aus:

https://<Name_des_API_Management-Dienstes>.azure-api.net/<API-URL-Suffix>/<http_triggered_function_name>

Wobei:

API-URL-Suffix

Das auf dem Arbeitsblatt notierte „API Management API URL Suffix“.

Name_der_HTTP-ausgelösten_Funktion

Der auf dem Arbeitsblatt notierte Name der HTTP-ausgelösten Funktion.

Notieren Sie sich auf dem Arbeitsblatt unter „External Function Name“ den Namen der erstellten externen Funktion.

Schritt 6: Externe Funktion testen

Testen Sie die externe Funktion, indem Sie sie aufrufen. Führen Sie beispielsweise einen SQL-Befehl ähnlich dem folgenden aus:

select my_external_function(42);

Der zurückgegebene Wert sollte wie folgt aussehen:

[0, 42]

wobei 42 der zurückgegebene Wert und 0 die Zeilennummer des zurückgegebenen Wertes ist.

Schritt 7: Sicherheitsrichtlinie für Azure API Management-Dienst (Proxydienst) festlegen

Die vorherigen Schritte ermöglichen es, dass Ihre importierten APIs (und damit Ihre Azure-Funktion) nicht nur von Snowflake aufgerufen werden können, sondern auch von anderen authentifizierten Clients, wie z. B. Anwendungen, die sich in Ihrem Azure AD-Mandantenbereich befinden oder die einen Dienstprinzipal in Ihrem Azure AD-Mandantenbereich haben. Wenn Sie nur Snowflake den Aufruf der Azure-Funktion erlauben möchten, müssen Sie eine zusätzliche Autorisierung erzwingen: die Token-Validierung.

Wenn Snowflake versucht, auf den API Management-Dienst zuzugreifen, präsentiert Snowflake ein JWT-Zugriffstoken, das von Azure AD bereitgestellt wurde. Der API Management-Dienst kann den JWT entweder validieren oder ihn ohne Validierung akzeptieren. Um eine Validierung des Tokens durch den API Managment-Dienst zu veranlassen, können Sie eine JWT-Validierungsrichtlinie hinzufügen, die die Regeln für die Validierung des Tokens angibt.

Bemerkung

Wenn Sie es vorziehen, in Ihrer JWT-Validierungsrichtlinie eine rollenbasierte Validierung zu verwenden, folgen Sie dem Link unten, um dem Snowflake-Dienstprinzipal eine Rolle zuzuweisen:

JWT-Validierungsrichtlinie für den Aufruf der Azure-Funktion durch Snowflake erstellen

Dieser Abschnitt zeigt, wie Sie eine Richtlinie für die Validierung eines JSON Web Token (JWT) angeben, das Snowflake autorisiert, Ihre Azure-Funktion aufzurufen. Die Validierungsrichtlinie („validate-JWT policy“) validiert die folgenden zwei Ansprüche im JWT:

  • Die Snowflake-Dienstprinzipal-Anwendungs-ID (die „requestor AppID“ oder einfach „appid“).

  • Die Zielanwendungs-App-ID (die „audience ID“ oder einfach „aud“) der Azure-Funktion.

Weitere Informationen zu Ansprüchen an JSON Web Tokens (JWTs), die von Azure Active Directory erhoben werden, finden Sie unter:

Mit den folgenden Schritten wird die importierte API für die Verwendung eines JSON Web Token konfiguriert.

  1. Wechseln Sie zum Bildschirm „API Management service“.

  2. Wählen Sie Ihren API Management-Dienst aus.

  3. Suchen Sie in der linken Spalte den Abschnitt „APIs“, und klicken Sie dann darunter auf die Option „APIs“.

  4. Klicken Sie in der Spalte, die „All APIs“ enthält, auf den Namen des API Managment-Dienstes, für den Sie eine Sicherheitsrichtlinie hinzufügen möchten.

  5. Suchen Sie nach „In-bound Processing“ (Eingehende Verarbeitung).

    1. Klicken Sie auf + Add policy.

    2. Klicken Sie auf validate-jwt.

    3. Geben Sie unter Header name den Wert Authorization ein.

    4. Fügen Sie die Validierung des JWT (JSON Web Token) hinzu, der von Snowflake für den Zugriff auf die Azure-Funktion bereitgestellt wird:

      1. Suchen Sie nach Required claims, und klicken Sie auf + Add claim.

      2. Geben Sie unter Name den Wert „aud“ (kurz für „audience“ (Zielgruppe)) ein.

      3. Suchen Sie innerhalb des erforderlichen Anspruchs nach Values, und klicken Sie auf +Add value.

        Fügen Sie die UUID hinzu, die Sie als „azure_ad_application_id“ im Befehl CREATE API INTEGRATION verwendet haben. Diese UUID haben Sie im Arbeitsblatt unter „Azure Function App AD Application ID“ erfasst.

    5. Fügen Sie einen separaten „claim“ (Anspruch) für Snowflake hinzu:

      1. Klicken Sie erneut auf + Add claim:

      2. Geben Sie unter Name die Zeichenfolge „appid“ ein.

      3. Klicken Sie innerhalb des Claims auf + Add value, und fügen Sie die Snowflake-App-ID hinzu.

        Wenn Sie noch keine Snowflake-App-ID haben, können Sie diese durch Ausführen der folgenden Schritte erhalten:

        1. Suchen Sie im Arbeitsblatt Ihren Eintrag zu AZURE_MULTI_TENANT_APP_NAME.

        2. Suchen Sie über das Suchfeld des Azure Portal nach Enterprise Applications.

          Dies bringt Sie zum Bildschirm Enterprise applications | All applications.

        3. Suchen Sie auf diesem Bildschirm nach AZURE_MULTI_TENANT_APP_NAME.

          Das Suchfeld ist nicht eindeutig beschriftet. Suchen Sie daher nach einem breiten Feld, das KEINE Bezeichnung hat.

          Wenn die beiden Werte für AZURE_MULTI_TENANT_APP_NAME nicht exakt übereinstimmen, dann führen Sie die Suche erneut aus, verwenden Sie diesmal aber nur die ersten Zeichen dieses Namens (wenn der Name einen Unterstrich enthält, dann schließen Sie weder den Unterstrich noch irgendwelche Zeichen nach dem Unterstrich ein).

        1. Kopieren Sie die Application-ID (die das Format einer UUID hat) in das Feld Values.

  6. Fügen Sie folgenden Wert in Open ID URLs ein:

    https://login.microsoftonline.com/<Mandanten-ID>/.well-known/openid-configuration

    Ersetzen Sie Mandanten-ID durch Ihren Azure AD-Mandanten-ID, die Sie im Abschnitt Vorbereiten des Erstellens einer externen Funktion auf Azure (direkt über dem Arbeitsblatt) notiert haben.

  7. Klicken Sie auf Save.

  8. Testen Sie die Änderung, indem Sie die externe Funktion erneut aufrufen.

IP-Adressen einschränken, von denen Aufrufe der Azure-Funktion (Remotedienst) akzeptiert werden (optional)

Zusätzlich zur Angabe einer JWT-Validierungsrichtlinie (oder der Verwendung einer rollenbasierten Autorisierung) können Sie die Sicherheit noch weiter erhöhen, indem Sie eine IP-Adressbeschränkung hinzufügen, sodass nur die IP des API Management-Dienstes auf die Azure-Funktionen-App zugreifen darf, die Ihre Azure-Funktion enthält. Weitere Informationen zur Einschränkung von IP-Adressen finden Sie unter:

Problembehandlung

Dieser Abschnitt enthält Informationen zur Problembehandlung für Azure.

Allgemeine Informationen zur Problembehandlung finden Sie unter Problembehandlung bei externen Funktionen.

Timeouts

Es gibt viele mögliche Ursachen für Timeouts. Bei Azure ist eine der möglichen Ursachen, dass die Azure-Funktionen-App nicht mit passender Skalierung geschrieben wurde. Stellen Sie sicher, dass Sie die Azure-Richtlinien für das Schreiben skalierbarer Funktionen befolgt haben.

Weitere Informationen zur Problembehandlung bei Skalierbarkeits- und Leistungsproblemen finden Sie in den allgemeinen Ausführungen zur Problembehandlung bei externen Funktionen.

Request failed for external function <Funktionsname>. Error: 401 ‚{ „statusCode“: 401, „message“: „Access denied due to missing subscription key. Make sure to include subscription key when making requests to an API.“ }‘

Möglicherweise müssen Sie die Abonnement-Anforderung für den API Management-Dienst deaktivieren.

Request failed for external function <Funktionsname>. Error: 401 ‚{ „statusCode“: 401, „message“: „Invalid JWT.“ }‘

  • Möglicherweise sind Sie ist die Festlegung der Sicherheitsrichtlinie für den Azure API Management-Dienst noch nicht komplett abgeschlossen. Das könnte beispielsweise Folgendes betreffen:

    • Das JWT wurde erstellt, aber nicht bearbeitet.

    • Es wurden erforderliche Ansprüche/Werte ausgelassen. Sie könnten beispielsweise den Anspruch für Snowflake angegeben haben, aber nicht den Remotedienst (Azure-Funktion), oder umgekehrt.

  • Möglicherweise haben Sie eine ungültige OpenID-URL verwendet.

SQL execution error: Failed to obtain Azure Active Directory access token.

Führen Sie die folgenden Schritte aus:

  • Vergewissern Sie sich, dass der Snowflake-Dienstprinzipal Zugriff auf Ihren Azure AD-Mandanten hat.

  • Überprüfen Sie, ob die Mandanten-ID und die Azure AD-Anwendungs-ID korrekt sind.

    Beachten Sie, dass Leerzeichen, einschließlich führende und nachstehende Leerzeichen, in ID-Feldern signifikant sind. Prüfen Sie auf falsche führende oder nachstehende Leerzeichen.

Einstellungen für die Azure-Funktion unter dem Menüpunkt Authentication/Authorization können nicht geändert werden

Beim Erstellen Ihrer Azure-Funktion können Sie die Einstellungen für diese Funktion möglicherweise nicht unter dem Menü Authentication/Authorization ändern. Dies ist der Fall, wenn alle der folgenden Punkte wahr sind:

  • Ihre Azure-Funktion wird unter Linux ausgeführt und nicht unter Microsoft Windows.

  • Sie planen die Verwendung der Azure AD-Authentifizierung/Autorisierung für Ihre Azure-Funktion.

  • Sie verwenden den „Consumption“-Tarif von Azure (und nicht der „Premium“-Tarif).

Azure AD-Authentifizierung ist im Linux-Verbrauchstarif für Azure-Funktionen nicht verfügbar. Sie müssen einen App Service-Tarif oder Premium-Tarif verwenden, um sich mit Azure AD zu authentifizieren.

Mögliche Lösungen sind die folgenden: