Introdução à API de Leitura de Metadados Assíncronos do SharePoint (AMR)

A API de Leitura de Metadados Assíncronos do SharePoint (AMR) permite a exportação assíncrona de metadados do SharePoint e do OneDrive.

Utilize a API AMR para exportar metadados do SharePoint para migração incremental e validação pós-migração.

A AMR foi concebida exclusivamente para cenários de importação. Apresenta uma baixa escalabilidade ao processar pedidos de metadados, permissões ou versões. Não podemos fornecer garantias de desempenho para a utilização de AMR em cenários de exportação de dados, como migrações entre inquilinos.

Novidades

Janeiro de 2024

Reformatámos este documento para trazer clareza e erros corretos.

Descrição geral dos passos de exportação

Exporte metadados do SharePoint em três passos:

Aprovisionar os contentores de destino e a fila

Importante

Utilize a API GetMigrationJobProgress para obter a tarefa de migração status.

O aprovisionamento de Filas do Azure para a tarefa de migração status controlo já não é necessário. A descontinuação do Azure Filas está prevista para o segundo semestre de 2026. Até lá, o Azure Filas permanecerá disponível para obtenção de status.

Utilize ProvisionMigrationContainers o método para aprovisionar os contentores. Veja Utilizar Contentores do Armazenamento de Blobs do Azure e Filas do Azure com a API de Migração para obter detalhes. Também pode utilizar os seus próprios contentores e filas, se necessário.

Utilizar CreateSPAsyncReadJob o método para iniciar a exportação

Utilize CreateSPAsyncReadJob o método para exportar metadados de um único URL ou CreateSPAsyncReadJobWithMultiUrl de vários URLs, se necessário. Veja Referência da API AMR para obter detalhes.

Obtenha atualizações incrementais com ChangeToken a funcionalidade.

Ambos os métodos devolvem o ID da Tarefa, que pode ser utilizado para controlar a exportação status.

Veja Referência da API AMR para obter detalhes.

A verificar status

Importante

Utilize a API GetMigrationJobProgress para obter a tarefa de migração status.

O aprovisionamento de Filas do Azure para a tarefa de migração status controlo já não é necessário. A descontinuação do Azure Filas está prevista para o segundo semestre de 2026. Até lá, o Azure Filas permanecerá disponível para obtenção de status.

Verifique a Fila do Azure fornecida para exportar status. Monitorize os eventos conforme listado em Eventos para obter detalhes.

A API AMR exporta metadados no contentor de manifesto fornecido, numa pasta com o nome JobID. Verifique se os ficheiros de Manifesto têm o formato e a validação dos metadados.

A API AMR divide pacotes de manifesto superiores a 25 MB em múltiplos ficheiros de manifesto por pedido.

Prática recomendada

A API AMR é poderosa. Garanta um bom desempenho para alcançar a escala para projetos de migração de grandes dimensões.

Exportar segurança e permissões no nível superior, se possível

A exportação de segurança com IncludeSecurity consome mais recursos e atrasa a exportação. É mais rápido exportar estes metadados na pasta de nível superior primeiro e, em seguida, exportar as crianças sem eles.

Exportação de metadados num único item

Utilize o Microsoft Graph em vez de AMR.

Pastas com menos de 10 000 itens

Utilize CreateSPAsyncReadJobWithMultiUrl para combinar os URLs de várias pastas numa única tarefa de exportação.

Pastas com 10 000 a 1 milhão de itens

Utilize CreateSPAsyncReadJobe defina readOptionIncludeDirectDescendantsOnly como false. Este valor é a predefinição.

Pastas aninhadas com mais de 1 milhão de itens

Planeie cuidadosamente ao dividir pastas em tarefas. A contagem de objetos nas tarefas de exportação é o fator principal do desempenho da exportação.

Este exemplo mostra como exportar metadados de pastas aninhadas com mais de 1 milhão de itens. A API AMR tem o desempenho mais elevado quando a contagem de itens é grande.

• Utilize CreateSPAsyncReadJob o método no URL de raiz, por exemplo: www.contoso.com/my-resource-documente defina readOptionIncludeDirectDescendantsOnly como true.
• Utilize SMTotalFileCount o atributo para obter a contagem de ficheiros em pastas.
• Continue a utilizar createSPAsyncReadJob o método ao nível da subpasta, em cada uma das subpastas, se a pasta tiver mais de 10 000 itens.
• Utilize CreateSPAsyncReadJobWithMultiUrl o método , combinando subpastas com menos de 10 000 itens.

Desempenho

A API AMR processa tarefas através de um mecanismo de fila com definições de gestão de cargas de trabalho pré-configuradas. A API AMR processa as tarefas numa base de melhor esforço, sem Contrato de Nível de Serviço (SLA) ou desempenho garantido.

Linha de base de desempenho testada em laboratório

Testámos o desempenho numa definição de laboratório. A API AMR exportou cerca de 400 itens por segundo para cada objeto de 250 K, no caso médio. O pico de desempenho atingiu 700 itens por segundo.

Vários fatores afetam o desempenho da vida real. Esses fatores incluem:

• O número de itens que estão a ser exportados
• A forma como a API de AMR é implementada
• Limitação

Otimizar o desempenho da migração

Para garantir um desempenho ideal para os seus projetos de migração, é importante planear cuidadosamente, especialmente ao lidar com migrações em grande escala. Para obter mais informações sobre como estimar períodos de tempo e otimizar o desempenho, veja o nosso guia de desempenho.

Estou a ver mensagens de limitação

Para garantir boas experiências de utilizador para todos os clientes do Microsoft 365, o SharePoint utiliza a limitação para proteger a infraestrutura do SharePoint. Evite ser limitado ao seguir as orientações de limitação.

Migrações inquilino a inquilino

A AMR não se destina a cenários em que os conteúdos de um inquilino do SharePoint são movidos para outro. Este tipo de migração requer a utilização de muitas opções de leitura com muitos recursos. O longo tempo de processamento destas opções de leitura atrasa significativamente a migração geral.

A Microsoft não fornece nenhuma garantia de desempenho neste cenário. Utilize Graph ou CSOM conforme necessário.