Módulos de Deploy WebAssembly (WASM) e definições de grafos

Os grafos de fluxo de dados do Operações IoT do Azure suportam módulos WebAssembly (WASM) para processamento personalizado de dados na edge. Você pode implantar lógica de negócios personalizada e transformações de dados como parte de seus pipelines de fluxo de dados.

Importante

Atualmente, os gráficos de fluxo de dados suportam apenas endpoints MQTT, Kafka e OpenTelemetry. Outros tipos de endpoints como Data Lake, Microsoft Fabric OneLake, Azure Data Explorer e Local Storage não são suportados.

Importante

Atualmente, o único conector que suporta definições de grafos para processamento personalizado é o conector HTTP/REST.

Importante

Atualmente, a interface Web do Operations Experience só permite criar e visualizar artefactos de gráfico de fluxo de dados obtidos a partir do Azure Container Registry (ACR) e, no caso das transformações incorporadas, do mcr.microsoft.com. Para saber mais, consulte Operations experience web UI apenas exibe artefactos de grafos de fluxo de dados provenientes de Azure Container Registry (ACR) e mcr.microsoft.com.

Pré-requisitos

  • Um endpoint de registo que aponta para o registo de contentores de onde queres extrair módulos e gráficos. Para mais informações, consulte Configurar endpoints do registo. Para começar sem configurar o seu próprio registo, use o endpoint de exemplo público descrito em ghcr.io.

Para enviar os seus próprios módulos e grafos para um registo privado como o Azure Container Registry (ACR), também precisa de:

  • Acesso a um registo de contentores como o ACR para armazenar módulos e grafos WASM.
  • A CLI ORAS (OCI Registry As Storage) para enviar módulos WASM para o registo.

Os CLI do Azure exemplos deste artigo usam variáveis de ambiente para que possas definir cada valor uma vez e depois copiar e colar os comandos as-is. Se estiver a usar o ambiente Operações IoT do Azure Codespaces do quickstart, estas variáveis já estão definidas para si e pode saltar este passo. Caso contrário, defina as seguintes variáveis de ambiente no seu shell antes de executar os comandos.

Os seguintes scripts definem as variáveis de ambiente mais usadas:

Variável de ambiente Description
SUBSCRIPTION_ID O ID da subscrição que contém a sua instância Operações IoT do Azure.
RESOURCE_GROUP O nome do grupo de recursos que contém a sua instância do Operações IoT do Azure.
AIO_INSTANCE_NAME O nome da sua instância do Operações IoT do Azure. Para listar as suas instâncias, execute az iot ops list -o table.
CLUSTER_NAME O nome do cluster Kubernetes com Azure Arc que hospeda a sua instância.
LOCATION A região do Azure a utilizar para novos recursos, por exemplo eastus. 
SUBSCRIPTION_ID=<subscription-id>
RESOURCE_GROUP=<resource-group-name>
AIO_INSTANCE_NAME=<instance-name>
CLUSTER_NAME=<cluster-name>
LOCATION=<region>

Só precisa de definir as variáveis que este artigo utiliza. Este artigo pode usar variáveis adicionais de ambiente para nomes de recursos que escolher. O artigo explica como posicioná-los onde são apresentados.

Visão geral

Os módulos WASM em gráficos de fluxo de dados e conectores do Operações IoT do Azure permitem-lhe processar dados na extremidade com alto desempenho e segurança. O WASM corre num ambiente sandbox e suporta Rust e Python.

Use módulos pré-construídos de um registo público

Pode usar os módulos de exemplo pré-construídos do WASM e as definições de grafos que são publicados no Registo de Contenedores público do GitHub (ghcr.io) sob azure-samples/explore-iot-operations.

Observação

ghcr.iorequer uma troca de tokens autenticados antes de servir sequer artefactos públicos, e o runtime atual do Operações IoT do Azure não realiza a troca anónima. Configure o ponto final public-ghcr com um segredo para obtenção de artefactos assente num token de acesso pessoal (PAT) do GitHub com o âmbito read:packages, em vez de recorrer à autenticação anónima. Para os passos finais e secretos, veja Usar um registo público.

Artefactos de exemplo disponíveis

Depois de criar o public-ghcr ponto final de registo, faça referência ao mesmo nos seus gráficos de fluxo de dados utilizando registryEndpointRef: public-ghcr. Como o host do endpoint do registo é ghcr.io, inclua o caminho do repositório azure-samples/explore-iot-operations nas referências de artefactos. Os seguintes módulos de exemplo e definições de grafos estão disponíveis:

Artifact Description
azure-samples/explore-iot-operations/graph-simple:1.0.0 Definição simples de grafo de conversão de temperatura
azure-samples/explore-iot-operations/graph-complex:1.0.0 Definição de grafo de processamento multi-sensor
azure-samples/explore-iot-operations/temperature:1.0.0 Módulo de conversão de temperatura (Fahrenheit para Celsius)
azure-samples/explore-iot-operations/window:1.0.0 Módulo de janelas baseado no tempo
azure-samples/explore-iot-operations/snapshot:1.0.0 Módulo de processamento de imagem e deteção de objetos
azure-samples/explore-iot-operations/format:1.0.0 Módulo de conversão de formato de imagem
azure-samples/explore-iot-operations/humidity:1.0.0 Módulo de processamento de dados de humidade
azure-samples/explore-iot-operations/collection:1.0.0 Módulo de agregação de dados multi-sensor
azure-samples/explore-iot-operations/enrichment:1.0.0 Módulo de enriquecimento de metadados
azure-samples/explore-iot-operations/filter:1.0.0 Módulo de filtragem de dados

Observação

As definições públicas de grafos de exemplo usam referências de módulos que incluem o azure-samples/explore-iot-operations caminho do repositório, por exemplo azure-samples/explore-iot-operations/temperature:1.0.0. Este caminho é necessário porque o host do endpoint do registo é ghcr.io. Se copiares os artefactos para o teu próprio repositório, certifica-te de que as referências aos módulos na definição do teu grafo correspondem aos caminhos para onde carregas os artefactos do módulo.

Para usar o gráfico simples com o registo público, veja o Exemplo 1: Implementação básica com um módulo WASM e usar public-ghcr como nome do endpoint do registo.

Utilizar um registo privado

Se precisares de usar módulos personalizados ou quiseres alojar as tuas próprias cópias dos módulos de exemplo, cria um registo privado de contentores como o Azure Container Registry (ACR).

Configurar o registro de contêiner

O Operações IoT do Azure precisa de um registo de contentores para extrair módulos WASM e definições de grafos. Pode usar o Azure Container Registry (ACR) ou outro registo compatível com OCI. Para criar uma instância ACR, veja Deploy Azure Container Registry. Depois de o registo existir, crie um endpoint de registo que aponte para ele – veja Criar um endpoint de registo.

Instalar a CLI do ORAS

Use a CLI do ORAS para enviar módulos WASM e definições de gráficos para o registro do contêiner. Para obter instruções de instalação, consulte Instalar o ORAS.

Extrair módulos de exemplo do registro público

Use módulos de exemplo pré-construídos:

# Pull sample modules and graphs
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/temperature:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/window:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/snapshot:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/format:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/humidity:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/collection:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/enrichment:1.0.0
oras pull ghcr.io/azure-samples/explore-iot-operations/filter:1.0.0

Carregar módulos para o seu repositório

Depois de ter os módulos e gráficos de exemplo, envie-os para o registro do contêiner. Defina a ACR_NAME variável ambiente para o nome do seu Azure Container Registry.

Importante

A experiência de operações descobre artefactos pelo tipo de meio de configuração OCI, não pelo tipo de meio de camada. Quando envia artefactos para um registo, tem de definir os tipos de media corretos, caso contrário os artefactos não aparecerão na interface de experiência de operações:

Tipo de artefato Tipo de meio de configuração OCI obrigatório Tipo de meio de camada exigido
Definição de grafo application/vnd.microsoft.aio.graph.v1+yaml application/yaml
Módulo WASM application/vnd.module.wasm.content.layer.v1+wasm application/wasm

Se usar um pipeline CI/CD ou outras ferramentas para copiar artefatos entre registos, verifique se preserva estes tipos de suportes. Algumas ferramentas removem ou substituem metadados de artefactos durante a transferência, o que faz com que os artefactos desapareçam silenciosamente da experiência operacional. Para obter mais informações, consulte Requisitos de artefatos do Registo.

Escolha um layout de artefacto

Os nomes dos artefactos que utiliza quando carrega grafos e módulos determinam as referências aos módulos de que necessita dentro da definição do grafo. Para contextualização sobre a relação entre o anfitrião do ponto final do registo, o caminho do artefacto e a referência do módulo, consulte Caminhos de artefacto e referências de módulos de grafo.

Para os gráficos de exemplo do Azure, preserva o caminho do repositório de exemplos quando copiares artefactos para o teu próprio registo. As definições de grafos referenciam módulos que usam esse caminho:

<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0

Use artifact: azure-samples/explore-iot-operations/graph-simple:1.0.0 no gráfico de fluxo de dados. A definição de grafo usa module: "azure-samples/explore-iot-operations/temperature:1.0.0".

Para os seus próprios gráficos, pode escolher um layout plano:

<YOUR_ACR_NAME>.azurecr.io/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/temperature:1.0.0

artifact: graph-simple:1.0.0 Use no gráfico de fluxo de dados e module: "temperature:1.0.0" dentro da definição do grafo.

Ou escolhe o teu próprio layout aninhado:

<YOUR_ACR_NAME>.azurecr.io/factory/graphs/graph-simple:1.0.0
<YOUR_ACR_NAME>.azurecr.io/factory/graphs/temperature:1.0.0

artifact: factory/graphs/graph-simple:1.0.0 Use no gráfico de fluxo de dados e module: "factory/graphs/temperature:1.0.0" dentro da definição do grafo.

Para garantir que os gráficos e módulos são visíveis na interface web da experiência de operações, adicione as flags --config e --artifact-type como mostrado no exemplo seguinte.

# Log in to your ACR
az acr login --name $ACR_NAME

# Push modules to your registry
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-simple:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-simple.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/graph-complex:1.0.0 --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml graph-complex.yaml:application/yaml --disable-path-validation
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/window:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm window.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/snapshot:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm snapshot.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/format:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm format.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/humidity:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm humidity.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/collection:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm collection.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/enrichment:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm enrichment.wasm:application/wasm
oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/filter:1.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm filter.wasm:application/wasm

Sugestão

Você também pode enviar seus próprios módulos e criar gráficos personalizados, consulte Configuração de gráficos de fluxo de dados personalizados.

Atualizar um módulo num grafo em execução

Pode atualizar um módulo WASM num grafo em execução sem parar o grafo. Isto é útil quando se quer atualizar a lógica de um operador sem parar o fluxo de dados. Por exemplo, para atualizar o módulo de conversão de temperatura da versão 1.0.0 para 2.0.0 no layout do artefacto de Azure exemplo, carregue a nova versão da seguinte forma:

oras push $ACR_NAME.azurecr.io/azure-samples/explore-iot-operations/temperature:2.0.0 --artifact-type application/vnd.module.wasm.content.layer.v1+wasm temperature.wasm:application/wasm

Observação

Se empurrares novo conteúdo para a mesma etiqueta (por exemplo, sobrescrevendo azure-samples/explore-iot-operations/temperature:1.0.0), o grafo de fluxo de dados capta automaticamente o módulo atualizado sem configuração adicional. No entanto, se empurrares para uma nova etiqueta (por exemplo, azure-samples/explore-iot-operations/temperature:2.0.0), também tens de atualizar a definição do grafo YAML para referenciar a nova versão e voltar a empurrar o artefacto do grafo.

Desenvolver módulos WASM personalizados

Para criar lógica de processamento de dados personalizada para os seus grafos de fluxo de dados, desenvolva módulos WebAssembly em Rust ou Python. Os módulos personalizados permitem implementar lógica de negócios especializada, transformações de dados e análises que não estão disponíveis nos operadores internos.

Para obter orientações abrangentes sobre o desenvolvimento, incluindo:

  • Configurando seu ambiente de desenvolvimento
  • Criação de operadores em Rust e Python
  • Noções básicas sobre o modelo de dados e as interfaces
  • Construindo e testando seus módulos

Consulte Desenvolver módulos WebAssembly para gráficos de fluxo de dados.

Para obter informações detalhadas sobre como criar e configurar as definições de gráfico YAML que definem seus fluxos de trabalho de processamento de dados, consulte Configurar definições de gráfico WebAssembly.

Requisitos de artefactos de registro

A experiência operacional utiliza metadados de artefactos OCI para descobrir e apresentar gráficos e módulos. Compreender estes requisitos é importante quando constróis pipelines personalizados de CI/CD, copias artefactos entre registos ou resolves problemas com artefactos em falta na interface.

Como funciona a descoberta de artefactos

Quando envias um artefacto para um registo com ORAS, o manifesto OCI inclui dois campos relevantes:

  • Tipo de media de configuração: Identifica que tipo de artefacto é este. A experiência operacional filtra neste campo para encontrar grafos e módulos.
  • Tipo de media em camadas: Descreve o formato de conteúdo do ficheiro real (YAML ou WASM).

A experiência de operação utiliza o tipo de meio de configuração para a descoberta, em vez do tipo de meio de camada. Se o tipo de meio de configuração estiver em falta ou incorreto, o artefacto existe no registo mas não aparece na interface.

Tipos de media obrigatórios

Tipo de artefato Tipo de media de configuração (--config ou --artifact-type) Tipo de mídia de camada
Definição de grafo application/vnd.microsoft.aio.graph.v1+yaml application/yaml
Módulo WASM application/vnd.module.wasm.content.layer.v1+wasm application/wasm

Para definições de grafos, passa o tipo de meio de configuração com a --config flag. Defina a REGISTRY variável ambiente para o seu anfitrião do registo (por exemplo, <your-registry>.azurecr.io):

oras push $REGISTRY/my-graph:1.0.0 \
  --config /dev/null:application/vnd.microsoft.aio.graph.v1+yaml \
  graph.yaml:application/yaml \
  --disable-path-validation

Para módulos WASM, passe-a com a --artifact-type flag:

oras push $REGISTRY/my-module:1.0.0 \
  --artifact-type application/vnd.module.wasm.content.layer.v1+wasm \
  module.wasm:application/wasm

Considerações sobre pipeline de integração e entrega contínua (CI/CD)

Se usar pipelines automatizados para copiar ou promover artefatos entre registos (por exemplo, de um registo de staging para um registo de produção), verifique se os pipelines preservam os metadados de artefatos OCI. Algumas ferramentas removem ou substituem o tipo de meio de configuração durante a transferência, o que faz com que os artefactos desapareçam silenciosamente da experiência operacional.

Para verificar se um artefacto tem os metadados corretos após a transferência, inspecione o seu manifesto:

oras manifest fetch $REGISTRY/my-graph:1.0.0 | jq '{mediaType, configMediaType: .config.mediaType}'

A saída deve mostrar:

{
  "mediaType": "application/vnd.oci.image.manifest.v1+json",
  "configMediaType": "application/vnd.microsoft.aio.graph.v1+yaml"
}

Se configMediaType mostrar um valor genérico como application/vnd.oci.empty.v1+json, os metadados foram eliminados e o artefacto precisa de ser reenviado com os parâmetros corretos.

Conteúdo relacionado

  • Last updated on