Etapa 1: criar o serviço remoto (Azure Function) no Portal

Este tópico fornece instruções detalhadas para a criação de um Azure Function para uso como serviço remoto para sua função externa.

Neste tópico:

Etapa anterior

Planejamento de uma função externa para o Azure

Criação do aplicativo Azure Functions

Há várias maneiras possíveis de criar um serviço remoto. Esta seção mostra como criar um serviço remoto que é implementado como uma função JavaScript.

Esta função externa é síncrona. Para obter mais informações sobre a criação de uma função externa assíncrona, consulte Criação de uma função assíncrona no Azure.

Crie um aplicativo Azure Functions para servir como um recipiente para a(s) função(ões) que você criar posteriormente:

  1. Entre no Portal do Azure se ainda não tiver feito isso.

  2. Crie o aplicativo Azure Functions seguindo as instruções da documentação da Microsoft: Aplicativo Azure Functions.

    Ao seguir as instruções, lembre-se do seguinte:

    • Ao inserir um nome no campo Function App Name, registre também o nome no campo Azure Function app name da sua planilha de rastreamento.

    • Quando solicitado a escolher como Publish, selecione Code.

    • Algumas restrições se aplicam ao criar várias aplicativos no mesmo grupo de recursos. Para obter mais detalhes, consulte a documentação da Microsoft: Serviço de Aplicativo do Azure.

    O Snowflake fornece uma função de “echo” de amostra no Node.js. Para usar essa função de amostra para começar:

    • Quando solicitado o Runtime stack, selecione Node.js.

    • Quando for solicitada a versão do Node.js, selecione a versão 12.

    • Quando perguntado em qual OS executar a função, escolha “Windows” ou “Linux”.

      • Se você estiver criando apenas uma função de demonstração, o Snowflake recomenda selecionar “Windows”.

        Os aplicativos de função do Linux não podem ser editados no Portal do Azure. Os usuários devem publicar o código pela interface do Visual Studio Code.

      • Se você quiser executar seu Azure Function no Linux em vez de no Microsoft Windows, consulte a documentação da Microsoft: Azure Functions.

        A autenticação do Azure AD não está disponível no Linux quando se utiliza o plano de preços “Consumo” para Azure Functions. Você deve usar um plano de preços “Serviço de Aplicativo” ou plano de preços “Premium” para se autenticar com o Azure AD.

        Para obter mais detalhes, consulte a documentação da Microsoft: Azure AD.

Criar um Azure Function acionado por HTTP

Após criar seu aplicativo Azure Functions (contêiner), você precisa criar um Azure Functions no contêiner. Essa função atua como o serviço remoto.

A Microsoft permite que as Azure Functions sejam chamadas (“acionadas”) de diferentes maneiras. Uma função externa do Snowflake invoca um serviço remoto por meio de um comando HTTP POST, portanto o Azure Function que você cria deve ser uma função “acionada por HTTP”.

Dica

Você pode usar as instruções fornecidas pela Microsoft para criar a função acionada por HTTP:

Entretanto, o Snowflake fornece instruções personalizadas que incluem detalhes adicionais e código de amostra, sugerindo um nível de autorização diferente daquele da Microsoft. Sugerimos o uso das instruções personalizadas em vez das instruções da Microsoft.

Criar a função

Para realizar as tarefas descritas nesta seção, você deve estar na tela Function App do Portal do Azure. O nome do seu aplicativo Azure Functions deve estar exibido, normalmente perto do canto superior esquerdo da tela.

Para criar a função acionada por HTTP:

  1. Na árvore de menus do lado esquerdo, procure a seção intitulada Functions. Nessa seção, clique no item rotulado Functions para adicionar uma função.

  2. Clique no botão + Add.

  3. Selecione HTTP trigger da lista de possíveis acionadores à direita.

  4. Digite o nome a ser usado para sua função acionada por HTTP.

    Registre esse nome no campo HTTP-Triggered Function name da sua planilha de rastreamento.

  5. Digite o Authorization level.

    O Snowflake recomenda escolher Function como nível de autorização.

    Para obter mais informações sobre possíveis níveis de autorização, consulte a documentação da Microsoft: Funções acionadas por HTTP.

  6. Clique no botão intitulado Add.

    Isto leva você a uma tela que mostra o nome da função e, abaixo dela, a palavra Function.

  7. Na árvore de menus no lado esquerdo, clique em Code + Test.

  8. Substitua o código padrão pelo seu próprio código.

    Uma amostra de código para uma função “echo” JavaScript é fornecida abaixo.

    A função lê cada linha, depois copia a linha para a saída (resultados). O número da linha também está incluído na saída. A saída é retornada como parte de um dicionário multinível.

    Essa função aceita e retorna dados no mesmo formato (JSON) que o Snowflake envia e lê. Para obter mais detalhes sobre formatos de dados, consulte Formatos de dados de entrada e saída do serviço remoto .

    Normalmente, a função retorna o código 200 HTTP. Se nenhuma linha for passada para a função (isto é, se o corpo da solicitação estiver vazio), a função retorna o código de erro 400.

    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."
           };
       }
    };
    
    Copy
  9. Clique no botão Save acima do código.

Testar a função

Para testar o Azure Function acionada por HTTP que você acabou de criar, cole os seguintes dados de amostra no campo Body e clique no botão Test/Run:

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

O conteúdo de saída deve ser semelhante ao seguinte:

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

Observe que a formatação pode ser diferente do que é mostrado acima.

Definição dos requisitos de autorização para o aplicativo Azure Functions

Quando uma função externa é chamada, o Snowflake envia um comando HTTP POST ao serviço de proxy (por exemplo, o serviço de gerenciamento de API do Azure), que retransmite o POST ao serviço remoto (por exemplo, o Azure Function).

Cada uma dessas duas etapas deve ter requisitos de autorização. Portanto, você normalmente especifica:

  • A autorização necessária para chamar o Serviço de gerenciamento de API.

  • A autorização necessária para chamar funções no aplicativo Azure Functions que contém seu Azure Function.

Esta seção descreve como solicitar autorização para seu aplicativo Azure Functions. O Serviço de gerenciamento de API é criado posteriormente, por isso seus requisitos de autorização também são especificados posteriormente.

Quando o Snowflake se autentica com seu aplicativo Azure Functions, o Snowflake usa o fluxo de concessão de credenciais do cliente OAuth com o Azure AD.

Para obter mais detalhes sobre o fluxo de concessão de credenciais do cliente, consulte a documentação da Microsoft: credencial do cliente.

Esse fluxo de credenciais do cliente requer um aplicativo Azure AD que representa o aplicativo Azure Functions.

Esta seção inclui instruções para a criação do registro do aplicativo Azure AD para o aplicativo Azure Functions. Por exemplo, você pode definir seu aplicativo Azure Functions para exigir autenticação Azure AD. Para configurar a autorização via Azure AD, você deve:

  • Criar um registro de aplicativo Azure AD, que é uma entidade baseada no Azure AD que representa uma identidade ou identificador de recurso (ou seja, o que você deseja proteger).

  • Associe o aplicativo Azure AD ao aplicativo Azure Functions para o qual você deseja requerer autenticação.

Nota

Para Azure Functions, a maneira mais rápida de criar um aplicativo Azure AD é habilitar a Autenticação do Azure AD, conforme documentado abaixo. Se você estiver usando um serviço remoto diferente de um Azure Function, use a página App registrations para criar um novo registro de aplicativo Azure AD para seu serviço remoto.

Para obter mais detalhes sobre o registro de aplicativos, consulte a documentação da Microsoft:

Habilitação da autenticação de serviços de aplicativos para o aplicativo Azure Functions

Antes de executar as etapas abaixo, você deve estar na tela Function App para seu aplicativo Azure Functions.

  1. No painel de menu à esquerda, procure a seção chamada Settings e clique em Authentication.

    Se a margem esquerda mostrar o menu Developer (com Code + Test, Integration etc.) e se você tiver uma barra de rolagem na parte inferior de sua tela, tente deslizar a barra de rolagem para a esquerda para retornar à seção Function App ou App Service, e depois procure por Settings.

  2. Clique no botão Add identity provider.

  3. No menu suspenso Identity provider, selecione Microsoft.

  4. Para App registration type, selecione Create new app registration.

  5. No campo Name, digite o nome do seu aplicativo.

  6. Para Supported account types, selecione Current tenant - Single tenant.

  7. Para Restrict access, selecione Require authentication.

  8. Para Unauthenticated requests, selecione HTTP 401 Unauthorized.

  9. Clique em Next: Permissions. Revise as permissões.

  10. Clique em Add. É criado um novo aplicativo Azure AD e é exibida a página do aplicativo.

  11. Clique no link que mostra o nome do seu aplicativo para acessar a página do seu aplicativo Azure AD.

  12. Encontre o campo Application (client) ID.

    Registre essa ID no campo Azure Function App AD Application ID da sua planilha de rastreamento.

    Importante

    Certifique-se de copiar o ID, não o nome do aplicativo Azure AD. O ID deve conter um UUID.

Próxima etapa

Etapa 2: criar o serviço de proxy (serviço de gerenciamento de API do Azure) no Portal