Este artigo foi traduzido automaticamente. A tradução pode conter imprecisões.
Alternar para a versão original em inglês.
Ctrlk
linkedinx-twitter
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Migração para a Log Ingestion API

A Microsoft está a descontinuar a Log Analytics HTTP Data Collector API. Migre o RealmJoin para a DCR-based Logs Ingestion API com o módulo RealmJoin PowerShell.

Visão geral

O RealmJoin grava os seus registos de auditoria, operacionais e de runbook no seu próprio workspace do Log Analytics. Até agora, fazia-o através do Azure Monitor API HTTP Data Collector, que autentica com a chave partilhada do workspace.

A Microsoft termina o suporte para essa API em 14 de setembro de 2026. O sucessor é a API de Ingestão de Logs (chamada API de Ingestão de Logs no Portal RealmJoin), que se baseia em Regras de Coleta de Dados (DCRs) e autenticação Microsoft Entra ID em vez de uma chave partilhada. O RealmJoin suporta-a, e a mudança é realizada com o módulo PowerShell do RealmJoin.

Esta página só se aplica se Log Analytics já estiver configurado para o seu tenant. Se não estiver, não há nada para migrar — a mesma página de definições oferece um comando que configura imediatamente um workspace na API de Ingestão de Logs. Ainda assim, recomendamos configurá-lo, para que os seus registos de auditoria, operacionais e de runbook sejam armazenados no seu próprio tenant.

Algo ficará danificado na data de desativação?

Muito provavelmente, nada. A documentação atual da Microsoft descreve uma suave descontinuação: os antigos endpoints deixam de ser suportados a partir dessa data, mas não deixam de aceitar dados, e a ingestão continua a funcionar desde que os clientes usem TLS 1.2 ou mais recente. A formulação mais rígida do anúncio original de 2023 — de que os endpoints simplesmente ficariam indisponíveis — está desatualizada.

Ainda assim, a migração é recomendada: o caminho antigo não tem suporte, depende de uma chave partilhada e não recebe mais correções.

O que muda

Antes — API Data Collector

  • Autenticação com o workspace chave partilhada ("Chave de Workspace do Cliente")

  • Um registo de aplicação Entra ID pertencente ao cliente com um segredo de cliente

  • Tabelas AuditLogs_CL, OperationalLogs_CL, RunbookLogs_CL

  • Configurado manualmente no Portal

Depois — API de Ingestão de Logs

  • Autenticação com Microsoft Entra ID, sem chave partilhada

  • O RealmJoin Azure Resources service principal, com âmbito limitado ao workspace e às suas regras

  • Tabelas RJAuditLogs_CL, RJOperationalLogs_CL, RJRunbookLogs_CL

  • Implementado e mantido pelo módulo PowerShell do RealmJoin

A migração reutiliza o seu existente workspace, por isso os seus registos existentes permanecem onde estão. O RealmJoin consulta as tabelas antigas e novas lado a lado, o que significa que os dados históricos continuam visíveis no Portal após a migração.

O que a migração implementa

Executar o comando de migração na sua subscrição cria:

  • O RealmJoin Azure Resources service principal no seu tenant Entra ID (se ainda não existir)

  • Três tabelas personalizadas no seu workspace existente: RJAuditLogs_CL, RJOperationalLogs_CL, RJRunbookLogs_CL

  • Uma Regra de Coleta de Dados por tabela (dcr-rj-aud-logs-*, dcr-rj-op-logs-*, dcr-rj-rb-logs-*), cada uma com o seu próprio endpoint de ingestão direto

  • Exatamente dois tipos de atribuição de função para o RealmJoin, e nada além disso:

    • Log Analytics Reader no workspace, para que o Portal possa consultar os seus registos

    • Monitoring Metrics Publisher em cada uma das três Regras de Coleta de Dados, para que o RealmJoin possa escrever nelas

O RealmJoin não recebe qualquer outra permissão na sua subscrição. A implementação é idempotente — voltar a executar o mesmo comando é seguro e aplica apenas o que estiver em falta.

Pré-requisitos

No Portal RealmJoin

  • Uma função que concede acesso à área Definições (CanReadSettingsDetails, consulte Permissões disponíveis). A página Definições gera o comando de migração, incluindo um token de integração de curta duração.

Na máquina que executa o PowerShell

  • PowerShell 7 ou posterior

  • Acesso à PowerShell Gallery para instalar o módulo RealmJoin

  • O Az.Accounts, Az.Resources e Az.Automation módulos — o módulo RealmJoin instala-os automaticamente nas versões fixadas, para o utilizador atual

Permissões da conta com que inicia sessão

  • Microsoft Entra ID: permissão para criar service principals, por exemplo Application Administrator, Cloud Application Administrator ou Global Administrator. Só é necessário na primeira vez, quando o service principal RealmJoin Azure Resources ainda não existe.

  • Subscrição do Azure: permissão para implementar no grupo de recursos do workspace e para criar atribuições de função nele — por exemplo Owner, ou Contributor combinado com User Access Administrator / Role Based Access Control Administrator.

  • O início de sessão ocorre através de Connect-AzAccount, que usa a Azure PowerShell aplicação de primeira parte. Os tenants que restringem o consentimento do utilizador podem precisar de conceder primeiro consentimento de administrador a essa aplicação.

O grupo de recursos e o workspace do Log Analytics já existem no seu caso — a migração não os cria. Os comandos do Portal são pré-preenchidos com a sua subscrição atual, grupo de recursos e nome do workspace.

Onde executar os comandos

Execute os comandos numa sessão local do PowerShell numa estação de trabalho administrativa — da mesma forma como executaria o script de integração do RealmJoin.

Use uma recém-aberta sessão do PowerShell e evite Azure Cloud Shell. O módulo RealmJoin requer versões exatas dos Az.* módulos. Se uma versão diferente de um Az módulo já estiver carregada na sessão — o que normalmente acontece no Cloud Shell — o módulo não consegue recuperar e termina com uma mensagem de conflito de versões. Fechar a sessão e abrir uma nova resolve isso.

Não é necessária uma sessão elevada ("Executar como administrador"): os módulos são instalados com -Scope CurrentUser.

Migração

1

Abra as definições do Log Analytics no Portal

Navegue para Definições → Log Analytics (https://portal.realmjoin.com/settings/log-analytics-configuration).

Enquanto o seu tenant ainda estiver na API Data Collector, a página mostra o aviso "Migrar para a API de Ingestão de Logs (Recomendado)" juntamente com um bloco de comando pronto a copiar. Use o Copiar botão para o copiar.

2

Verifique o comando copiado

O comando tem o seguinte aspeto, com os seus próprios valores preenchidos:

  • As primeiras linhas instalam ou atualizam o módulo RealmJoin e importam-no.

  • Set-RJLogAnalyticsWorkspace executa a migração propriamente dita e regista o resultado no RealmJoin usando o -Token.

  • Grant-RJUpdateComplianceWorkspaceAccess só aparece se tiver configurado um workspace do Update Compliance. Concede ao RealmJoin Log Analytics Reader nesse workspace para que os dados do Windows Update continuem a funcionar sem o seu próprio registo de aplicação.

Certifique-se de que -ResourceGroupName, -WorkspaceName e -SubscriptionId estão presentes e apontam para o seu existente workspace. Se -WorkspaceName estiver em falta, o módulo cria um novo workspace em vez de migrar o existente, e os seus registos antigos e novos acabam em locais diferentes. Adicione manualmente o parâmetro em falta, se necessário.

Sobre 6>&1: estes comandos comunicam o seu progresso no fluxo Information do PowerShell. A 6>&1 redireção apresenta esse output na consola — sem ela, não verá quaisquer mensagens de progresso.

3

Execute o comando

Cole o bloco numa nova sessão do PowerShell e execute-o. O token é válido por cerca de uma hora — se tiver expirado, recarregue a página de definições e copie o comando novamente.

Ser-lhe-á pedido que inicie sessão com Connect-AzAccount. Se a sua conta tiver acesso a vários tenants ou subscrições, o módulo pede-lhe que escolha.

A implementação então comunica cada recurso à medida que é criado: o service principal, as tabelas personalizadas, as Regras de Coleta de Dados e as atribuições de função. Uma única execução geralmente demora alguns minutos.

Quer ver primeiro o que aconteceria? Acrescente -WhatIf a Set-RJLogAnalyticsWorkspace para uma pré-visualização What-If do Azure Resource Manager. Note que iniciar sessão e instalar os Az módulos continua a acontecer, porque a pré-visualização precisa de ambos.

Terminar sessão depois: o início de sessão no Azure permanece ativo depois de o comando terminar. Quando terminar, execute Disconnect-AzAccount para terminar sessão da sessão existente.

4

Verifique no Portal

Volte a Definições → Log Analytics e selecione Atualizar.

A página mostra agora a configuração da API de Ingestão de Logs — subscrição, grupo de recursos, nome do workspace, ID do workspace do cliente e ID do tenant — como campos só de leitura, uma vez que estas definições passam agora a ser mantidas pelo módulo PowerShell. Em Avançadas pode rever os endpoints, nomes das regras e nomes dos streams das três Regras de Coleta de Dados.

Selecione Verificar problemas de configuração para verificar se todas as permissões do Azure necessárias estão em vigor no workspace e em cada Regra de Coleta de Dados.

5

Confirme que os registos chegam

Abra Registo de auditoria, o Registos de runbook ou os registos operacionais e confirme que aparecem novas entradas. As entradas existentes de antes da migração continuam também visíveis.

O Azure precisa de alguns minutos para disponibilizar uma tabela personalizada recém-criada e a respetiva regra. Se nada chegar imediatamente, aguarde um pouco e atualize.

Após a migração

Mantenha por enquanto o registo de aplicação antigo

As entradas históricas em AuditLogs_CL, OperationalLogs_CL e RunbookLogs_CL continuam a ser lidas com o seu registo de aplicação e segredo de cliente existentes. O Portal consulta as tabelas antigas e novas em paralelo.

Não elimine o registo de aplicação e continue a renovar o respetivo segredo de cliente, enquanto ainda quiser ver dados de registos de antes da migração. Apenas a chave partilhada do workspace deixou de ser necessária para o RealmJoin — já não é usada para escrita.

Quando os dados antigos expirarem da sua retenção do workspace, pode remover o registo de aplicação.

Manter o esquema atualizado

Se o RealmJoin alargar o esquema de registos numa versão futura, a página de definições mostra um aviso de que o esquema do Log Analytics implementado está desatualizado, juntamente com o comando para o atualizar. Esse é o mesmo Set-RJLogAnalyticsWorkspace comando — volte a executá-lo e as tabelas e regras são atualizadas no local.

Resolução de problemas

"O módulo RealmJoin está desatualizado - a execução não pode prosseguir"

Cada cmdlet verifica uma vez por sessão se está a executar a versão publicada mais recente do módulo. Instale a versão atual e, em seguida, feche a sessão e abra uma nova:

É reportado um conflito de versões do módulo

Um Az.* módulo numa versão diferente daquela a que o módulo RealmJoin fixa já está carregado na sessão. Isto não pode ser corrigido na sessão em execução — feche o PowerShell, abra uma nova sessão e execute o comando novamente. Esta é também a razão para não usar Azure Cloud Shell.

"Precisa de aprovação do administrador" ou um erro de consentimento durante o início de sessão

O início de sessão usa a Azure PowerShell aplicação de primeira parte. Se o seu tenant restringir o consentimento do utilizador, um administrador tem de conceder uma vez consentimento de administrador a essa aplicação.

A implementação falha ao criar atribuições de função

Criar as Log Analytics Reader e Monitoring Metrics Publisher atribuições requer uma função que possa gerir o acesso — por exemplo Owner, User Access Administrator ou Role Based Access Control Administrator no grupo de recursos ou subscrição. Contributor sozinha não é suficiente.

As atribuições de função que já existem são detetadas e ignoradas, pelo que voltar a executar o comando depois de corrigir as permissões é seguro.

A implementação falha com um erro sobre a região do workspace

A implementação visa a região do grupo de recursos. Se o seu workspace existente estiver numa região diferente da do respetivo grupo de recursos, o Azure rejeita a alteração, porque a localização de um workspace existente não pode ser modificada. Nesse caso, contacte o suporte do RealmJoin.

O token já não é aceite

O token de integração no comando gerado tem curta duração (cerca de uma hora). Recarregue Definições → Log Analytics no Portal, copie o comando novamente e volte a executá-lo. A própria implementação do Azure é idempotente, pelo que uma segunda execução não causa danos.

O workspace do Update Compliance está numa subscrição diferente

Grant-RJUpdateComplianceWorkspaceAccess procura o workspace na subscrição atualmente selecionada. Se o workspace do Update Compliance estiver noutro local, passe a subscrição explicitamente:

Última atualização

Isto foi útil?