Monitorar cenário em funções duráveis - Exemplo de observador meteorológico

Artigo
07/27/2024

O padrão de monitor refere-se a um processo recorrente flexível em um fluxo de trabalho - por exemplo, sondagem até que certas condições sejam atendidas. Este artigo explica um exemplo que usa funções duráveis para implementar o monitoramento.

Descrição geral do cenário

Este exemplo monitora as condições meteorológicas atuais de um local e alerta um usuário por SMS quando o céu está limpo. Você pode usar uma função regular acionada pelo temporizador para verificar o tempo e enviar alertas. No entanto, um problema com essa abordagem é o gerenciamento do tempo de vida. Se apenas um alerta deve ser enviado, o monitor precisa se desativar depois que o tempo claro for detetado. O padrão de monitoramento pode encerrar sua própria execução, entre outros benefícios:

Os monitores são executados em intervalos, não em horários: um gatilho de temporizador é executado a cada hora, um monitor aguarda uma hora entre as ações. As ações de um monitor não se sobrepõem, a menos que especificado, o que pode ser importante para tarefas de longa execução.
Os monitores podem ter intervalos dinâmicos: o tempo de espera pode mudar com base em alguma condição.
Os monitores podem ser encerrados quando alguma condição for atendida ou ser encerrados por outro processo.
Os monitores podem ter parâmetros. O exemplo mostra como o mesmo processo de monitoramento do tempo pode ser aplicado a qualquer local e número de telefone solicitados.
Os monitores são escaláveis. Como cada monitor é uma instância de orquestração, vários monitores podem ser criados sem a necessidade de criar novas funções ou definir mais código.
Os monitores integram-se facilmente em fluxos de trabalho maiores. Um monitor pode ser uma seção de uma função de orquestração mais complexa ou uma suborquestração.

Configuração

Configurando a integração do Twilio

Este exemplo envolve o uso do serviço Twilio para enviar mensagens SMS para um telefone celular. O Azure Functions já tem suporte para o Twilio por meio da associação do Twilio, e o exemplo usa esse recurso.

A primeira coisa que você precisa é de uma conta Twilio. Você pode criar um gratuitamente em https://www.twilio.com/try-twilio. Depois de ter uma conta, adicione as três configurações de aplicativo a seguir ao seu aplicativo de função.

Nome de definição de aplicação	Descrição do valor
TwilioAccountSid	O SID da sua conta Twilio
TwilioAuthToken	O token de autenticação para sua conta Twilio
TwilioPhoneNumber	O número de telefone associado à sua conta Twilio. Isso é usado para enviar mensagens SMS.

Configurando a integração do Weather Underground

Este exemplo envolve o uso da API Weather Underground para verificar as condições meteorológicas atuais de um local.

A primeira coisa que você precisa é de uma conta Weather Underground. Você pode criar um gratuitamente em https://www.wunderground.com/signup. Depois de ter uma conta, você precisa adquirir uma chave de API. Pode fazê-lo visitando https://www.wunderground.com/weather/apie, em seguida, selecionando Configurações de Chave. O plano do Stratus Developer é gratuito e suficiente para executar este exemplo.

Depois de ter uma chave de API, adicione a seguinte configuração de aplicativo ao seu aplicativo de função.

Nome de definição de aplicação	Descrição do valor
TempoUndergroundApiKey	A sua chave API do Weather Underground.

As funções

Este artigo explica as seguintes funções no aplicativo de exemplo:

E3_Monitor: Uma função orquestradora que chama E3_GetIsClear periodicamente. Ele chama E3_SendGoodWeatherAlert se E3_GetIsClear retorna true.
E3_GetIsClear: Uma função de atividade que verifica as condições meteorológicas atuais de um local.
E3_SendGoodWeatherAlert: Uma função de atividade que envia uma mensagem SMS via Twilio.

E3_Monitor função orquestradora

C#
JavaScript

[FunctionName("E3_Monitor")]
public static async Task Run([OrchestrationTrigger] IDurableOrchestrationContext monitorContext, ILogger log)
{
    MonitorRequest input = monitorContext.GetInput<MonitorRequest>();
    if (!monitorContext.IsReplaying) { log.LogInformation($"Received monitor request. Location: {input?.Location}. Phone: {input?.Phone}."); }

    VerifyRequest(input);

    DateTime endTime = monitorContext.CurrentUtcDateTime.AddHours(6);
    if (!monitorContext.IsReplaying) { log.LogInformation($"Instantiating monitor for {input.Location}. Expires: {endTime}."); }

    while (monitorContext.CurrentUtcDateTime < endTime)
    {
        // Check the weather
        if (!monitorContext.IsReplaying) { log.LogInformation($"Checking current weather conditions for {input.Location} at {monitorContext.CurrentUtcDateTime}."); }

        bool isClear = await monitorContext.CallActivityAsync<bool>("E3_GetIsClear", input.Location);

        if (isClear)
        {
            // It's not raining! Or snowing. Or misting. Tell our user to take advantage of it.
            if (!monitorContext.IsReplaying) { log.LogInformation($"Detected clear weather for {input.Location}. Notifying {input.Phone}."); }

            await monitorContext.CallActivityAsync("E3_SendGoodWeatherAlert", input.Phone);
            break;
        }
        else
        {
            // Wait for the next checkpoint
            var nextCheckpoint = monitorContext.CurrentUtcDateTime.AddMinutes(30);
            if (!monitorContext.IsReplaying) { log.LogInformation($"Next check for {input.Location} at {nextCheckpoint}."); }

            await monitorContext.CreateTimer(nextCheckpoint, CancellationToken.None);
        }
    }

    log.LogInformation($"Monitor expiring.");
}

[Deterministic]
private static void VerifyRequest(MonitorRequest request)
{
    if (request == null)
    {
        throw new ArgumentNullException(nameof(request), "An input object is required.");
    }

    if (request.Location == null)
    {
        throw new ArgumentNullException(nameof(request.Location), "A location input is required.");
    }

    if (string.IsNullOrEmpty(request.Phone))
    {
        throw new ArgumentNullException(nameof(request.Phone), "A phone number input is required.");
    }
}

O orquestrador requer um local para monitorar e um número de telefone para enviar uma mensagem quando o tempo ficar claro no local. Esses dados são passados para o orquestrador como um objeto fortemente tipado MonitorRequest .

A função E3_Monitor usa o function.json padrão para funções de orquestrador.

{
  "bindings": [
    {
      "name": "context",
      "type": "orchestrationTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

Aqui está o código que implementa a função:

const df = require("durable-functions");
const moment = require("moment");

module.exports = df.orchestrator(function* (context) {
    const input = context.df.getInput();
    context.log(
        "Received monitor request. location: " +
            (input ? input.location : undefined) +
            ". phone: " +
            (input ? input.phone : undefined) +
            "."
    );

    verifyRequest(input);

    const endTime = moment.utc(context.df.currentUtcDateTime).add(6, "h");
    context.log(
        "Instantiating monitor for " +
            input.location.city +
            ", " +
            input.location.state +
            ". Expires: " +
            endTime +
            "."
    );

    while (moment.utc(context.df.currentUtcDateTime).isBefore(endTime)) {
        // Check the weather
        context.log(
            "Checking current weather conditions for " +
                input.location.city +
                ", " +
                input.location.state +
                " at " +
                context.df.currentUtcDateTime +
                "."
        );
        const isClear = yield context.df.callActivity("E3_GetIsClear", input.location);

        if (isClear) {
            // It's not raining! Or snowing. Or misting. Tell our user to take advantage of it.
            context.log(
                "Detected clear weather for " +
                    input.location.city +
                    ", " +
                    input.location.state +
                    ". Notifying " +
                    input.phone +
                    "."
            );

            yield context.df.callActivity("E3_SendGoodWeatherAlert", input.phone);
            break;
        } else {
            // Wait for the next checkpoint
            const nextCheckpoint = moment.utc(context.df.currentUtcDateTime).add(30, "s");
            context.log(
                "Next check for " +
                    input.location.city +
                    ", " +
                    input.location.state +
                    " at " +
                    nextCheckpoint.toString()
            );

            yield context.df.createTimer(nextCheckpoint.toDate()); // accomodate cancellation tokens
        }
    }

    context.log("Monitor expiring.");
});

function verifyRequest(request) {
    if (!request) {
        throw new Error("An input object is required.");
    }
    if (!request.location) {
        throw new Error("A location input is required.");
    }
    if (!request.phone) {
        throw new Error("A phone number input is required.");
    }
}

Esta função orquestradora executa as seguintes ações:

Obtém o MonitorRequest que consiste no local a ser monitorado e no número de telefone para o qual ele envia uma notificação por SMS.
Determina o tempo de expiração do monitor. O exemplo usa um valor codificado para brevidade.
Chama E3_GetIsClear para determinar se há céu limpo no local solicitado.
Se o tempo estiver limpo, ligue para E3_SendGoodWeatherAlert para enviar uma notificação por SMS para o número de telefone solicitado.
Cria um temporizador durável para retomar a orquestração no próximo intervalo de sondagem. O exemplo usa um valor codificado para brevidade.
Continua em execução até que a hora UTC atual passe o tempo de expiração do monitor ou um alerta SMS seja enviado.

Várias instâncias do orquestrador podem ser executadas simultaneamente chamando a função do orquestrador várias vezes. O local a ser monitorado e o número de telefone para enviar um alerta SMS podem ser especificados. Por fim, observe que a função orchestrator não está sendo executada enquanto aguarda o temporizador, então você não será cobrado por isso.

E3_GetIsClear função de atividade

Tal como acontece com outros exemplos, as funções de atividade auxiliar são funções regulares que usam a ligação de activityTrigger gatilho. A função E3_GetIsClear obtém as condições meteorológicas atuais usando a API Weather Underground e determina se o céu está limpo.

C#
JavaScript

[FunctionName("E3_GetIsClear")]
public static async Task<bool> GetIsClear([ActivityTrigger] Location location)
{
    var currentConditions = await WeatherUnderground.GetCurrentConditionsAsync(location);
    return currentConditions.Equals(WeatherCondition.Clear);
}

O function.json é definido do seguinte modo:

{
  "bindings": [
    {
      "name": "location",
      "type": "activityTrigger",
      "direction": "in"
    }
  ],
  "disabled": false
}

E aqui está a implementação.

const request = require("request");

const clearWeatherConditions = [
    "Overcast",
    "Clear",
    "Partly Cloudy",
    "Mostly Cloudy",
    "Scattered Clouds",
];

module.exports = function (context, location) {
    getCurrentConditions(location)
        .then(function (data) {
            const isClear = clearWeatherConditions.includes(data.weather);
            context.done(null, isClear);
        })
        .catch(function (err) {
            context.log(`E3_GetIsClear encountered an error: ${err}`);
            context.done(err);
        });
};

function getCurrentConditions(location) {
    return new Promise(function (resolve, reject) {
        const options = {
            url: `https://api.wunderground.com/api/${process.env["WeatherUndergroundApiKey"]}/conditions/q/${location.state}/${location.city}.json`,
            method: "GET",
            json: true,
        };
        request(options, function (err, res, body) {
            if (err) {
                reject(err);
            }
            if (body.error) {
                reject(body.error);
            }
            if (body.response.error) {
                reject(body.response.error);
            }
            resolve(body.current_observation);
        });
    });
}

E3_SendGoodWeatherAlert função de atividade

A função E3_SendGoodWeatherAlert usa a ligação Twilio para enviar uma mensagem SMS notificando o usuário final de que é um bom momento para uma caminhada.

C#
JavaScript

    [FunctionName("E3_SendGoodWeatherAlert")]
    public static void SendGoodWeatherAlert(
        [ActivityTrigger] string phoneNumber,
        ILogger log,
        [TwilioSms(AccountSidSetting = "TwilioAccountSid", AuthTokenSetting = "TwilioAuthToken", From = "%TwilioPhoneNumber%")]
            out CreateMessageOptions message)
    {
        message = new CreateMessageOptions(new PhoneNumber(phoneNumber));
        message.Body = $"The weather's clear outside! Go take a walk!";
    }

internal class WeatherUnderground
{
    private static readonly HttpClient httpClient = new HttpClient();
    private static IReadOnlyDictionary<string, WeatherCondition> weatherMapping = new Dictionary<string, WeatherCondition>()
    {
        { "Clear", WeatherCondition.Clear },
        { "Overcast", WeatherCondition.Clear },
        { "Cloudy", WeatherCondition.Clear },
        { "Clouds", WeatherCondition.Clear },
        { "Drizzle", WeatherCondition.Precipitation },
        { "Hail", WeatherCondition.Precipitation },
        { "Ice", WeatherCondition.Precipitation },
        { "Mist", WeatherCondition.Precipitation },
        { "Precipitation", WeatherCondition.Precipitation },
        { "Rain", WeatherCondition.Precipitation },
        { "Showers", WeatherCondition.Precipitation },
        { "Snow", WeatherCondition.Precipitation },
        { "Spray", WeatherCondition.Precipitation },
        { "Squall", WeatherCondition.Precipitation },
        { "Thunderstorm", WeatherCondition.Precipitation },
    };

    internal static async Task<WeatherCondition> GetCurrentConditionsAsync(Location location)
    {
        var apiKey = Environment.GetEnvironmentVariable("WeatherUndergroundApiKey");
        if (string.IsNullOrEmpty(apiKey))
        {
            throw new InvalidOperationException("The WeatherUndergroundApiKey environment variable was not set.");
        }

        var callString = string.Format("http://api.wunderground.com/api/{0}/conditions/q/{1}/{2}.json", apiKey, location.State, location.City);
        var response = await httpClient.GetAsync(callString);
        var conditions = await response.Content.ReadAsAsync<JObject>();

        JToken currentObservation;
        if (!conditions.TryGetValue("current_observation", out currentObservation))
        {
            JToken error = conditions.SelectToken("response.error");

            if (error != null)
            {
                throw new InvalidOperationException($"API returned an error: {error}.");
            }
            else
            {
                throw new ArgumentException("Could not find weather for this location. Try being more specific.");
            }
        }

        return MapToWeatherCondition((string)(currentObservation as JObject).GetValue("weather"));
    }

    private static WeatherCondition MapToWeatherCondition(string weather)
    {
        foreach (var pair in weatherMapping)
        {
            if (weather.Contains(pair.Key))
            {
                return pair.Value;
            }
        }

        return WeatherCondition.Other;
    }
}

Nota

Você precisará instalar o Microsoft.Azure.WebJobs.Extensions.Twilio pacote Nuget para executar o código de exemplo.

A sua function.json é simples:

{
    "bindings": [
      {
        "name": "phoneNumber",
        "type": "activityTrigger",
        "direction": "in"
      },
      {
        "type": "twilioSms",
        "name": "message",
        "from": "%TwilioPhoneNumber%",
        "accountSidSetting": "TwilioAccountSid",
        "authTokenSetting": "TwilioAuthToken",
        "direction": "out"
      }
    ],
    "disabled": false
  }

E aqui está o código que envia a mensagem SMS:

module.exports = function (context, phoneNumber) {
    context.bindings.message = {
        body: `The weather's clear outside! Go take a walk!`,
        to: phoneNumber,
    };

    context.done();
};

Executar o exemplo

Usando as funções acionadas por HTTP incluídas no exemplo, você pode iniciar a orquestração enviando a seguinte solicitação HTTP POST:

POST https://{host}/orchestrators/E3_Monitor
Content-Length: 77
Content-Type: application/json

{ "location": { "city": "Redmond", "state": "WA" }, "phone": "+1425XXXXXXX" }

HTTP/1.1 202 Accepted
Content-Type: application/json; charset=utf-8
Location: https://{host}/runtime/webhooks/durabletask/instances/f6893f25acf64df2ab53a35c09d52635?taskHub=SampleHubVS&connection=Storage&code={SystemKey}
RetryAfter: 10

{"id": "f6893f25acf64df2ab53a35c09d52635", "statusQueryGetUri": "https://{host}/runtime/webhooks/durabletask/instances/f6893f25acf64df2ab53a35c09d52635?taskHub=SampleHubVS&connection=Storage&code={systemKey}", "sendEventPostUri": "https://{host}/runtime/webhooks/durabletask/instances/f6893f25acf64df2ab53a35c09d52635/raiseEvent/{eventName}?taskHub=SampleHubVS&connection=Storage&code={systemKey}", "terminatePostUri": "https://{host}/runtime/webhooks/durabletask/instances/f6893f25acf64df2ab53a35c09d52635/terminate?reason={text}&taskHub=SampleHubVS&connection=Storage&code={systemKey}"}

A instância E3_Monitor é iniciada e consulta as condições meteorológicas atuais para o local solicitado. Se o tempo estiver limpo, ele chama uma função de atividade para enviar um alerta; caso contrário, define um temporizador. Quando o temporizador expira, a orquestração é retomada.

Você pode ver a atividade da orquestração examinando os logs de função no portal do Azure Functions.

2018-03-01T01:14:41.649 Function started (Id=2d5fcadf-275b-4226-a174-f9f943c90cd1)
2018-03-01T01:14:42.741 Started orchestration with ID = '1608200bb2ce4b7face5fc3b8e674f2e'.
2018-03-01T01:14:42.780 Function completed (Success, Id=2d5fcadf-275b-4226-a174-f9f943c90cd1, Duration=1111ms)
2018-03-01T01:14:52.765 Function started (Id=b1b7eb4a-96d3-4f11-a0ff-893e08dd4cfb)
2018-03-01T01:14:52.890 Received monitor request. Location: Redmond, WA. Phone: +1425XXXXXXX.
2018-03-01T01:14:52.895 Instantiating monitor for Redmond, WA. Expires: 3/1/2018 7:14:52 AM.
2018-03-01T01:14:52.909 Checking current weather conditions for Redmond, WA at 3/1/2018 1:14:52 AM.
2018-03-01T01:14:52.954 Function completed (Success, Id=b1b7eb4a-96d3-4f11-a0ff-893e08dd4cfb, Duration=189ms)
2018-03-01T01:14:53.226 Function started (Id=80a4cb26-c4be-46ba-85c8-ea0c6d07d859)
2018-03-01T01:14:53.808 Function completed (Success, Id=80a4cb26-c4be-46ba-85c8-ea0c6d07d859, Duration=582ms)
2018-03-01T01:14:53.967 Function started (Id=561d0c78-ee6e-46cb-b6db-39ef639c9a2c)
2018-03-01T01:14:53.996 Next check for Redmond, WA at 3/1/2018 1:44:53 AM.
2018-03-01T01:14:54.030 Function completed (Success, Id=561d0c78-ee6e-46cb-b6db-39ef639c9a2c, Duration=62ms)

A orquestração é concluída assim que seu tempo limite é atingido ou o céu limpo é detetado. Você também pode usar a terminate API dentro de outra função ou invocar o webhook HTTP POST terminatePostUri referenciado na resposta 202 anterior. Para usar o webhook, substitua {text} pelo motivo da rescisão antecipada. O URL HTTP POST tem aproximadamente a seguinte aparência:

POST https://{host}/runtime/webhooks/durabletask/instances/f6893f25acf64df2ab53a35c09d52635/terminate?reason=Because&taskHub=SampleHubVS&connection=Storage&code={systemKey}

Próximos passos

Este exemplo demonstra como usar funções duráveis para monitorar o status de uma fonte externa usando temporizadores duráveis e lógica condicional. O próximo exemplo mostra como usar eventos externos e temporizadores duráveis para lidar com a interação humana.

Executar o exemplo de interação humana

Partilhar via