Erstellen einer externen Funktion auf Microsoft Azure über das Azure-Portal

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:

Planen einer externen Funktion auf Microsoft Azure

Voraussetzungen für das Erstellen einer externen Funktion auf Microsoft Azure

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:

  • Ein Snowflake-Konto, in dem Sie über ACCOUNTADMIN-Berechtigungen oder eine Rolle mit der Berechtigung CREATE INTEGRATION verfügen.

Die folgenden Informationen sollten bereits vorliegen:

Azure AD Tenant ID: _____________________________________

Dies ist eine UUID, die typischerweise so formatiert ist, dass es ähnlich aussieht wie „12345678-abcd-1234-efab-123456789012“, wobei jedes Nicht-Bindestrich-Zeichen eine hexadezimale Ziffer ist.

Wenn Sie Ihre 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.

Arbeitsblatt

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 App 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.)


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

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

API Management API URL suffix....: __________________________________________


---------------- Information about the API Integration and External Function -----------------

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

AZURE_MULTI_TENANT_APP_NAME......: _______________________________________________

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

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.

  • Wenn Sie gefragt werden, ob für Publish die Option Code oder Docker Container verwendet werden soll, wählen Sie Code.

  • Für das Erstellen mehrerer Apps in derselben Ressourcengruppe gelten einige Einschränkungen. Details finden Sie in der Dokumentation zum Microsoft Azure App-Dienst

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

    • Wählen Sie als Runtime stack die Option „Node.js“ aus.

    • Wählen Sie als Node.js-Version die Version 12 aus.

    • Wählen Sie als Betriebssystem, unter dem die Funktion ausgeführt werden soll, „Windows“ oder „Linux“ aus.

      • Wenn Sie lediglich eine Demo erstellen, dann empfiehlt Snowflake die Auswahl von „Windows“.

        Linux-Funktionen-Apps können im Azure Portal nicht bearbeitet werden. Benutzer müssen den Code mithilfe von Visual Studio Code veröffentlichen.

      • Wenn Sie möchten, dass Ihre Azure-Funktion unter Linux und nicht unter Microsoft Windows ausgeführt wird, finden Sie vielleicht folgende Informationen hilfreich:

        Microsoft Azure Functions-Dokumentation

        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.

        Weitere Informationen dazu finden Sie in der Azure AD-Dokumentation unter:

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.

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

(Wie Sie eine über HTTP ausgelöste Funktion erstellen, erklärt Microsoft in den folgenden Dokumenten:

Snowflake schlägt jedoch vor, die benutzerdefinierten Anweisungen unten zu verwenden).

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 in der Dokumentation für durch HTTP ausgelöste Funktionen.

  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.

    Diese Funktion akzeptiert Daten in demselben Format (JSON), das von Snowflake gesendet und gelesen wird. (Weitere Informationen zu Datenformaten finden Sie unter Eingangs- und Ausgangsdatenformate von Remotediensten.)

    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 die Azure-Funktion testen, indem Sie Beispieldaten bereitstellen und auf die Schaltfläche Test/Run klicken. Sie können die unten stehenden Beispieldaten in das Feld mit der Bezeichnung Body einfügen.

    {
         "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 unter: Clientanmeldinformationen.)

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 registrations, 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 Function 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 Dropdownmenü mit der Bezeichnung Action to take when request is not authenticated, und wählen Sie die Option Log in with Azure Active Directory aus.

  4. Wählen Sie unter Authentication Providers die Option Azure Active Directory aus, wenn sie nicht bereits ausgewählt ist.

  5. Klicken Sie auf Azure Active Directory, wodurch Sie zum Bildschirm Azure Active Directory Settings gelangen sollten.

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 die zweite Schaltfläche 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 führen Sie über das Microsoft Azure-Suchfenster am oberen Rand des Bildschirms App registrations eine Suche aus.

    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.

    Dadurch sollten Sie zum Bildschirm App registrations gelangen.

  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 App AD Application ID des Arbeitsblatts. (Stellen Sie sicher, dass Sie die ID und nicht den Azure AD-Anwendungsnamen kopieren. Die ID sollte eine 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 Feld „API Management service name“ des Arbeitsblatts 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–40 Minuten oder länger 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 den API URL suffix im Feld „API Management API URL suffix“ des Arbeitsblatts.

    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. Die Anleitung finden Sie unter:

    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. Wechseln Sie auf die Registerkarte Settings. Diese befindet sich neben der Registerkarte Design in dem Bereich des Bildschirms unter der Versionsnummer Ihrer API (z. B. REVISION 1).

  3. Wenn 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).

  4. 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 abschließen und die externe Funktion testen und danach die Sicherheitsrichtlinie für den Azure API Management-Dienst konfigurieren. Um das Debugging zu vereinfachen, wird bei dieser Anleitung zuerst die externe Funktion fertiggestellt und getestet.

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 etwa wie folgt aussehen:

    https://<api-management-service-name>.azure-api.net/<api_url_suffix>

    Sie finden den Wert für <Name_des_API_Management-Dienstes> im Arbeitsblatt unter „API Management service name“. Den Wert für <API-URL-Suffix> finden Sie im Arbeitsblatt unter „API Management API URL Suffix“.

    Ihre URL sollte ungefähr wir folgt aussehen:

    https://my-api-management-svc.azure-api.net/my-api-url-suffix

    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 Integration Name“. 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

Gehen Sie nun zurück zur Snowflake-Weboberfläche (wo Sie zuvor den Befehl CREATE API INTEGRATION eingegeben haben).

  1. Geben Sie den Befehl CREATE EXTERNAL FUNCTION ein. 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://<API_Management_service_name>.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.

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

  2. Wenn Sie den oben eingegebenen CREATE EXTERNAL FUNCTION-Befehl noch nicht ausgeführt haben, führen Sie ihn jetzt aus.

Schritt 6: Externe Funktion aufrufen

  1. Erteilen Sie gegebenenfalls einer oder mehreren Snowflake-Rollen die Berechtigung USAGE für die externe Funktion, damit diese Rollen die externe Funktion aufrufen können. (Eine Rolle muss über USAGE- oder OWNERSHIP-Berechtigung für diese externe Funktion verfügen.)

  2. Führen Sie Ihre Funktion aus, indem Sie Folgendes aufrufen:

    SELECT my_external_function(42, 'Adams');
    

    Wenn Sie den Funktionsnamen im Befehl CREATE EXTERNAL FUNCTION angepasst haben, dann ersetzen Sie „my_external_function“ durch den angepassten Namen.

    Der zurückgegebene Wert sollte wie folgt aussehen:

    [0, 42, "Adams"]
    

    wobei 42, "Adams" 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. Gehen 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 der API, für die Sie eine Sicherheitsrichtlinie hinzufügen möchten.

  5. Suchen Sie nach In-bound Processing.

    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 Anspruchs (Claim) auf + Add value, und fügen Sie im Feld Values die Snowflake-App-ID hinzu.

        Wenn Sie noch keine Snowflake-App-ID haben, können Sie diese durch Ausführen der folgenden Schritte ermitteln (die Snowflake-App-ID ist im Feld Application ID zu finden):

        1. Suchen Sie auf dem 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 für Unternehmensanwendungen hat keine Bezeichnung. Achten Sie auf ein breites Feld direkt über der Liste der Unternehmensanwendungen. In dem Feld könnte etwas Ähnliches stehen wie First 50 shown, to search all of your applications, enter a display name or the application ID.

          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).

        4. Suchen Sie den Application ID-Wert für AZURE_MULTI_TENANT_APP_NAME.

  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 Voraussetzungen für das Erstellen einer externen Funktion auf Microsoft 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:

Erstellen einer asynchronen Funktion auf Azure

Asynchrone externe Funktionen werden auf Azure unterstützt. Die Konzepte auf Azure sind ähnlich wie die Konzepte für das Erstellen von asynchronen Funktionen auf AWS. Das AWS-Codebeispiel kann jedoch nicht direkt für Azure verwendet werden, da Sie die entsprechenden Azure-Dienste wie Azure Functions und Azure Blob Storage nutzen müssen. Außerdem unterscheiden sich die Details der Navigation auf der Benutzeroberfläche der Cloudplattform.

Problembehandlung bei externen Funktionen auf Azure

Plattformunabhängige Symptome

Die tatsächlichen Rückgabewerte für einen Datentyp stimmen nicht mit den erwarteten Rückgabewerten überein

Achten Sie beim Übergeben von Argumenten an oder von einer externen Funktion darauf, dass die passenden Datentypen verwendet werden. Wenn der gesendete Wert nicht zum Datentyp des Empfängers passt, wird der Wert möglicherweise abgeschnitten oder auf andere Weise beschädigt.

Weitere Details dazu finden Sie unter Sicherstellen, dass Argumente der externen Funktion den Argumenten des Remotedienstes entsprechen.

Beim Aufrufen der Funktion mit SQL wird eine Meldung angezeigt, dass die Zeilennummerierung nicht korrekt ist

Mögliche Ursachen

Denken Sie daran, dass die von Ihnen innerhalb jedes Batches zurückgegebenen Zeilennummern monoton aufsteigende Ganzzahlen sein müssen, die bei 0 beginnen. Die Eingabezeilennummern müssen ebenfalls dieser Regel folgen, und jede Ausgabezeile muss mit der entsprechenden Eingabezeile übereinstimmen. So sollte beispielsweise die Ausgabe von Ausgabezeile 0 der Eingabe von Eingabezeile 0 entsprechen.

Mögliche Lösungen
  1. Stellen Sie sicher, dass die von Ihnen zurückgegebenen Zeilennummern mit den erhaltenen Zeilennummern übereinstimmen und dass jeder Ausgabewert die Zeilennummer der entsprechenden Eingabe verwendet. Das sollte funktionieren. Wenn dies nicht der Fall ist, sind möglicherweise die eingegebenen Zeilennummern nicht korrekt oder die Zeilen wurden nicht in der richtigen Reihenfolge zurückgegeben. Fahren Sie daher mit Schritt 2 fort.

  2. Stellen Sie sicher, dass die Ausgabezeilennummern bei 0 beginnen, um 1 erhöht werden und in der richtigen Reihenfolge sind.

Weitere Informationen zu Dateneingabe- und Datenausgabeformaten finden Sie unter Eingabe- und Ausgabedatenformate von Remotediensten.

Beim Versuch, die externe Funktion aufzurufen, wird die Meldung „Error parsing JSON: Invalid response“ angezeigt

Mögliche Ursachen

Die wahrscheinlichste Ursache ist, dass die vom Remotedienst zurückgegebenen JSON-Daten (z. B. AWS Lambda-Funktion) nicht korrekt erstellt wurde.

Mögliche Lösungen

Stellen Sie sicher, dass Sie ein Array von Arrays zurückgeben, wobei für jede empfangene Eingabezeile ein inneres Array zurückgegeben wird. Überprüfen Sie die Beschreibung des Ausgabeformats unter Von Snowflake empfangenes Datenformat.

Eine Fehlermeldung besagt, dass das Format des zurückgegebenen Werts nicht JSON ist

Mögliche Ursachen

Eine mögliche Ursache hierfür ist, dass Ihr Rückgabewert doppelte Anführungszeichen enthält.

Mögliche Lösungen

Obwohl JSON-Zeichenfolgen durch doppelte Anführungszeichen getrennt sind, sollte die Zeichenfolge selbst in den meisten Fällen nicht mit einem Anführungszeichen beginnen und enden. Wenn die eingebetteten doppelten Anführungszeichen falsch sind, entfernen Sie diese.

Eine Fehlermeldung besagt, dass die Funktion die falsche Anzahl von Zeilen erhält

Mögliche Ursachen

Der Remotedienst hat wahrscheinlich versucht, mehr oder weniger Zeilen zurückzugeben, als er erhalten hat. (Denken Sie daran, dass die Funktion, obwohl sie nominell skalar ist, möglicherweise im Feld „body“ des Parameters „event“ mehrere Zeilen empfängt und genau so viele Zeilen zurückgeben sollte, wie sie empfangen hat.)

Mögliche Lösungen

Stellen Sie sicher, dass der Remotedienst für jede erhaltene Zeile genau eine Zeile zurückgibt.

Plattformspezifische Symptome

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 unter Problembehandlung bei Skalierbarkeits- und Leistungsproblemen.

Error: 401 ‚{ „statusCode“: 401, „message“: „Access denied due to missing subscription key…“ }‘

Der vollständige Text der Meldung lautet:

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ögliche Ursachen

Die Abonnement-Anforderung des API Management-Dienstes könnte aktiviert sein.

Mögliche Lösungen

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

Error: 401 … Invalid JWT

Der vollständige Text der Meldung lautet:

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

Mögliche Ursachen
  • 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.

Mögliche Lösungen
  • Schließen Sie die Festlegung der Sicherheitsrichtlinie für den Azure API Management-Dienst ab. Überprüfen Sie z. B. das JWT, und stellen Sie sicher, dass Sie die erforderlichen Ansprüche/Werte eingefügt haben, einschließlich des Anspruchs für Snowflake und des Anspruchs für den Remotedienst (Azure Function).

  • Vergewissern Sie sich, dass Sie eine gültige Open ID URL verwendet haben.

Error: Failed to obtain Azure Active Directory access token.

Mögliche Lösungen

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.

Mögliche Ursachen

Dieses Problem kann auftreten, 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 den „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
  • Erstellen Sie die Azure-Funktion neu, und geben Sie an, dass sie unter Microsoft Windows und nicht unter Linux ausgeführt werden soll.

  • Überspringen Sie die Azure AD-Authentifizierung/Autorisierung für die Azure-Funktion, und:

    Wenn Sie diese Lösung wählen, müssen Sie die Azure AD-Anwendung manuell erstellen. (Sie können die Anleitung unter App-Registrierung verwenden).

    Wenn Sie die Azure AD-Anwendung manuell erstellen, notieren Sie sich auf dem Arbeitsblatt den „Azure Function AD app registration name“ und die „Azure Function App AD Application ID“.

  • Wechseln Sie vom „Consumption“-Tarif zum „Premium“-Tarif, oder verwenden Sie einen „App Service“-Tarif. Weitere Details dazu finden Sie unter:

    Konfigurieren eines Authentifizierungsanbieters

Error: 401 ‚{ „statusCode“: 401, „message“: „Access denied due to missing subscription key.“ }

Mögliche Ursachen

Der Proxydienst benötigt einen API-Schlüssel (auch „Abonnementschlüssel“ genannt), typischerweise zur Authentifizierung oder Abrechnung. Es wurde jedoch kein API-Schlüssel geliefert.

Mögliche Lösungen

Verwenden Sie den Befehl ALTER API INTEGRATION, um den korrekten API-Schlüssel anzugeben.

Error: 401 ‚{ „statusCode“: 401, „message“: „Access denied due to invalid subscription key.“ }‘

Mögliche Ursachen

Der Proxydienst benötigt einen API-Schlüssel (auch „Abonnementschlüssel“ genannt), typischerweise zur Authentifizierung oder Abrechnung. Der in der API_KEY-Klausel des CREATE API INTEGRATION-Befehls angegebene API-Schlüssel war falsch.

Mögliche Lösungen

Verwenden Sie den Befehl ALTER API INTEGRATION, um den korrekten API-Schlüssel anzugeben.