> For the complete documentation index, see [llms.txt](https://docs.realmjoin.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md).

# Migração para a API de Ingestão de Registos

A Microsoft está a descontinuar a API Log Analytics HTTP Data Collector. Migre o RealmJoin para a API de Ingestão de Registos baseada em DCR com o módulo PowerShell do RealmJoin.

## 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 **HTTP Data Collector API**, que se autentica com a chave partilhada do workspace.

A Microsoft termina o suporte para essa API em **14 de setembro de 2026**. O seu sucessor é a **Logs Ingestion API** (chamada *Log Ingestion API* no RealmJoin Portal), que se baseia em [Data Collection Rules (DCRs)](https://learn.microsoft.com/en-us/azure/azure-monitor/essentials/data-collection-rule-overview) e autenticação Microsoft Entra ID em vez de uma chave partilhada. O RealmJoin suporta-a, e a mudança é feita com o [módulo RealmJoin PowerShell](/pt/implementacao/onboarding-realmjoin-portal/advanced-setup.md).

{% hint style="info" %}
Esta página só se aplica se [Log Analytics](/pt/monitorizacao-e-registos/log-analytics.md) já estiver configurado para o seu Tenant. Se não estiver, não há nada a migrar — a mesma página de definições oferece um comando que configura um workspace na Log Ingestion API de imediato. Ainda assim, recomendamos configurá-lo, para que os seus registos de auditoria, operacionais e de runbook fiquem armazenados no seu próprio Tenant.
{% endhint %}

### Algo deixará de funcionar na data de descontinuação?

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

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

### O que muda

{% columns %}
{% column %}

#### Antes — Data Collector API

* Autenticação com a **chave partilhada** ("Chave do Workspace do cliente")
* Uma **registo de aplicação Entra ID pertencente ao cliente** com um segredo do cliente
* Tabelas `AuditLogs_CL`, `OperationalLogs_CL`, `RunbookLogs_CL`
* Configurado manualmente no Portal
  {% endcolumn %}

{% column %}

#### Depois — Log Ingestion API

* Autenticação com **Microsoft Entra ID**, sem chave partilhada
* O **RealmJoin Azure Resources** service principal, limitado ao workspace e às respetivas regras
* Tabelas `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Implementado e mantido pelo módulo RealmJoin PowerShell
  {% endcolumn %}
  {% endcolumns %}

A migração reutiliza o seu **existente** workspace, por isso os seus registos existentes ficam onde estão. O RealmJoin consulta as tabelas antiga e nova lado a lado, o que significa que os dados históricos permanecem 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 do Entra ID (se ainda não existir)
* Três tabelas personalizadas no seu workspace existente: `RJAuditLogs_CL`, `RJOperationalLogs_CL`, `RJRunbookLogs_CL`
* Uma Data Collection Rule por tabela (`dcr-rj-aud-logs-*`, `dcr-rj-op-logs-*`, `dcr-rj-rb-logs-*`), cada uma com o seu próprio ponto de ingestão direto
* Exatamente dois tipos de atribuição de funções para o RealmJoin, e nada além deles:
  * **Log Analytics Reader** no workspace, para que o Portal possa consultar os seus registos
  * **Monitoring Metrics Publisher** em cada uma das três Data Collection Rules, 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 só aplica o que estiver em falta.

## Pré-requisitos

### No RealmJoin Portal

* Uma função que concede acesso à área de Definições (`CanReadSettingsDetails`, veja [Permissões disponíveis](/pt/administracao-e-definicoes/permission/custom-roles/available-permissions.md)). A página de Definições gera o comando de migração, incluindo um token de entrada de curta duração.

### Na máquina que executa o PowerShell

* **PowerShell 7** ou posterior
* Acesso à [PowerShell Gallery](https://www.powershellgallery.com/packages/RealmJoin) 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 a qual 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 da 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ções nele — por exemplo *Owner*, ou *Contributor* combinado com *User Access Administrator* / *Role Based Access Control Administrator*.
* O início de sessão acontece 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.

{% hint style="info" %}
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 vêm pré-preenchidos com a sua subscrição atual, grupo de recursos e nome do workspace.
{% endhint %}

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

{% hint style="warning" %}
Use uma **recentemente aberta** sessão do PowerShell e evite o **Azure Cloud Shell**. O módulo RealmJoin requer versões exatas dos módulos `Az.*` . Se uma versão diferente de um `Az` já estiver carregado 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 isto.
{% endhint %}

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

## Migração

{% stepper %}
{% step %}

#### 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 Data Collector API, a página mostra o aviso **"Migrar para a API de Ingestão de Logs (Recomendado)"** juntamente com um bloco de comandos pronto a copiar. Use o botão **Copiar** para o copiar.
{% endstep %}

{% step %}

#### Verifique o comando copiado

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

```powershell
$latest = [version](Find-Module RealmJoin -Repository PSGallery -ErrorAction Stop).Version
if (-not (Get-Module -ListAvailable RealmJoin | Where-Object Version -ge $latest)) {
    Install-Module RealmJoin -Force -AllowClobber -ErrorAction Stop
}
Import-Module RealmJoin -Force
Set-RJLogAnalyticsWorkspace -ResourceGroupName "<ResourceGroupName>" -WorkspaceName "<WorkspaceName>" -SubscriptionId "<SubscriptionId>" -Token "<Token>" 6>&1
Grant-RJUpdateComplianceWorkspaceAccess -WorkspaceId "<WorkspaceId>" 6>&1
```

* 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 com o RealmJoin usando o `-Token`.
* `Grant-RJUpdateComplianceWorkspaceAccess` só aparece se tiver configurado um [workspace do Update Compliance](/pt/monitorizacao-e-registos/log-analytics.md#windows-update-for-business-reports). 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.

{% hint style="warning" %}
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.
{% endhint %}

{% hint style="info" %}
**Sobre `6>&1`:** estes comandos reportam o seu progresso no stream de Information do PowerShell. A `6>&1` redireção mostra essa saída no console — sem ela, não verá nenhuma mensagem de progresso.
{% endhint %}
{% endstep %}

{% step %}

#### 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 para iniciar 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 depois reporta cada recurso à medida que é criado: o service principal, as tabelas personalizadas, as Data Collection Rules e as atribuições de funções. Uma única execução normalmente demora alguns minutos.

{% hint style="info" %}
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.
{% endhint %}
{% endstep %}

{% step %}

#### Verificar no Portal

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

A página mostra agora a configuração da Log Ingestion API — 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 a ser mantidas pelo módulo PowerShell a partir de agora. Em **Avançadas** pode rever os endpoints, os nomes das regras e os nomes dos streams das três Data Collection Rules.

Selecione **Verificar problemas de configuração** para verificar se todas as permissões Azure necessárias estão presentes no workspace e em cada Data Collection Rule.
{% endstep %}

{% step %}

#### Confirme que os registos chegam

Abra [Registo de auditoria](/pt/monitorizacao-e-registos/audit-log.md), os [Registos de Runbook](/pt/automatizacao/runbooks/runbook-logs.md) ou os registos operacionais e confirme que aparecem novas entradas. As entradas existentes de antes da migração também continuam visíveis.

{% hint style="info" %}
O Azure precisa de alguns minutos para disponibilizar uma tabela personalizada recém-criada e a respetiva regra. Se nada aparecer imediatamente, espere um pouco e atualize.
{% endhint %}
{% endstep %}
{% endstepper %}

## 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` ainda são lidas com o seu **registo de aplicação e segredo do cliente existentes**. O Portal consulta as tabelas antiga e nova em paralelo.

{% hint style="warning" %}
Não elimine o registo de aplicação e continue a renovar o respetivo segredo do cliente enquanto ainda quiser ver dados de registo anteriores à migração. Apenas a **chave partilhada do workspace** já não é necessária para o RealmJoin — já não é usada para escrita.
{% endhint %}

Quando os dados antigos saírem da retenção do seu [workspace](https://learn.microsoft.com/en-us/azure/azure-monitor/logs/data-retention-archive?tabs=portal-1%2Cportal-2), pode remover o registo de aplicação.

### Manter o esquema atualizado

Se o RealmJoin expandir 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 — execute-o novamente e as tabelas e regras são atualizadas no local.

## Resolução de problemas

<details>

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

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

```powershell
Install-Module -Name RealmJoin -Force -Scope CurrentUser
```

</details>

<details>

<summary>É comunicado um conflito de versões do módulo</summary>

Um `Az.*` módulo numa versão diferente daquela fixada pelo módulo RealmJoin já está carregado na sessão. Isto não pode ser corrigido dentro da 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 o Azure Cloud Shell.

</details>

<details>

<summary>"É necessária aprovação de administrador" ou um erro de consentimento durante o início de sessão</summary>

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 terá de conceder consentimento de administrador a essa aplicação uma vez.

</details>

<details>

<summary>A implementação falha ao criar atribuições de funções</summary>

A criação das *Log Analytics Reader* e *Monitoring Metrics Publisher* atribuições requer uma função que possa gerir acesso — por exemplo *Owner*, *User Access Administrator* ou *Role Based Access Control Administrator* no grupo de recursos ou na subscrição. *Contributor* por si só não é suficiente.

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

</details>

<details>

<summary>A implementação falha com um erro relativo à região do workspace</summary>

A implementação tem como alvo 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.

</details>

<details>

<summary>O token já não é aceite</summary>

O token de entrada no comando gerado tem curta duração (cerca de uma hora). Atualize **Definições → Log Analytics** no Portal, copie novamente o comando e execute-o outra vez. A implementação no Azure em si é idempotente, por isso uma segunda execução não causa problemas.

</details>

<details>

<summary>O workspace do Update Compliance está numa subscrição diferente</summary>

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

```powershell
Grant-RJUpdateComplianceWorkspaceAccess -WorkspaceId "<WorkspaceId>" -SubscriptionId "<SubscriptionId>" 6>&1
```

</details>


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.realmjoin.com/pt/monitorizacao-e-registos/log-ingestion-api-migration.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.