> 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 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)](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 é realizada com o [módulo PowerShell do RealmJoin](/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 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.
{% endhint %}

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

{% columns %}
{% column %}

#### 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
  {% endcolumn %}

{% column %}

#### 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
  {% endcolumn %}
  {% endcolumns %}

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](/pt/administracao-e-definicoes/permission/custom-roles/available-permissions.md)). 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](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 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.

{% 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 são 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 **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.
{% 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 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.
{% 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 no 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 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.
{% 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 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.

{% 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 %}

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

{% step %}

#### 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.
{% endstep %}

{% step %}

#### Confirme que os registos chegam

Abra [Registo de auditoria](/pt/monitorizacao-e-registos/audit-log.md), o [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 continuam também 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 chegar imediatamente, aguarde 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` 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.

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

Quando os dados antigos expirarem da sua [retenção do 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 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

<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 publicada mais recente do módulo. Instale a versão atual e, em seguida, feche a sessão e abra uma nova:

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

</details>

<details>

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

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.

</details>

<details>

<summary>"Precisa de aprovação do 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 tem de conceder uma vez consentimento de administrador a essa aplicação.

</details>

<details>

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

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.

</details>

<details>

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

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.

</details>

<details>

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

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.

</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, passe 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 by asking a question.

Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters:

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

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case.

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.