Atualização assíncrona com a API REST

  • Artigo

Usando qualquer linguagem de programação que ofereça suporte a chamadas REST, você pode executar operações assíncronas de atualização de dados em seus modelos tabulares do Azure Analysis Services. Isso inclui a sincronização de réplicas somente leitura para expansão da consulta.

As operações de atualização de dados podem levar algum tempo, dependendo de uma série de fatores, incluindo volume de dados, nível de otimização usando partições, etc. Essas operações têm sido tradicionalmente invocadas com métodos existentes, como o uso de TOM (Tabular Object Model), cmdlets do PowerShell ou TMSL (Tabular Model Scripting Language). No entanto, esses métodos podem exigir conexões HTTP muitas vezes não confiáveis e de longa execução.

A API REST para Azure Analysis Services permite que operações de atualização de dados sejam realizadas de forma assíncrona. Usando a API REST, conexões HTTP de longa execução de aplicativos cliente não são necessárias. Há também outros recursos internos para confiabilidade, como repetições automáticas e confirmações em lote.

URL Base

O URL base segue este formato:

https://<rollout>.asazure.windows.net/servers/<serverName>/models/<resource>/

Por exemplo, considere um modelo chamado AdventureWorks em um servidor chamado myserver, localizado na região Oeste do Azure dos EUA. O nome do servidor é:

asazure://westus.asazure.windows.net/myserver

O URL base para este nome de servidor é:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/

Usando a URL base, os recursos e operações podem ser acrescentados com base nos seguintes parâmetros:

Diagram that shows asynchronous refresh logic.

  • Qualquer coisa que termine em s é uma coleção.
  • Qualquer coisa que termine com () é uma função.
  • Qualquer outra coisa é um recurso/objeto.

Por exemplo, você pode usar o verbo POST na coleção Refreshes para executar uma operação de atualização:

https://westus.asazure.windows.net/servers/myserver/models/AdventureWorks/refreshes

Autenticação

Todas as chamadas devem ser autenticadas com um token válido do Microsoft Entra ID (OAuth 2) no cabeçalho Autorização e devem atender aos seguintes requisitos:

  • O token deve ser um token de usuário ou uma entidade de serviço de aplicativo.

  • O token deve ter o público correto definido como https://*.asazure.windows.net.

  • O usuário ou aplicativo deve ter permissões suficientes no servidor ou modelo para fazer a chamada solicitada. O nível de permissão é determinado pelas funções dentro do modelo ou do grupo de administradores no servidor.

    Importante

    Atualmente, as permissões de função de administrador do servidor são necessárias.

POST /atualiza

Para executar uma operação de atualização, use o verbo POST na coleção /refreshes para adicionar um novo item de atualização à coleção. O cabeçalho Location na resposta inclui o ID de atualização. O aplicativo cliente pode se desconectar e verificar o status posteriormente, se necessário, porque é assíncrono.

Apenas uma operação de atualização é aceita de cada vez para um modelo. Se houver uma operação de atualização em execução atual e outra for enviada, o código de status HTTP de conflito 409 será retornado.

O corpo pode assemelhar-se ao seguinte:

{
    "Type": "Full",
    "CommitMode": "transactional",
    "MaxParallelism": 2,
    "RetryCount": 2,
    "Objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer"
        },
        {
            "table": "DimDate"
        }
    ]
}

Parâmetros

Não é necessário especificar parâmetros. O padrão é aplicado.

Nome Tipo Descrição Predefinido
Type Enumerar O tipo de processamento a ser executado. Os tipos são alinhados com os tipos de comando TMSL refresh: full, clearValues, calculate, dataOnly, automatic e defragment. Não há suporte para adicionar tipo. automático
CommitMode Enumerar Determina se os objetos serão confirmados em lotes ou somente quando concluídos. Os modos incluem: default, transactional, partialBatch. transacional
MaxParallelism Int Esse valor determina o número máximo de threads nos quais executar comandos de processamento em paralelo. Esse valor está alinhado com a propriedade MaxParallelism que pode ser definida no comando TMSL Sequence ou usando outros métodos. 10
RetryCount Int Indica o número de vezes que a operação será repetida antes de falhar. 0
Objects Matriz Uma matriz de objetos a serem processados. Cada objeto inclui: "tabela" ao processar a tabela inteira ou "tabela" e "partição" ao processar uma partição. Se nenhum objeto for especificado, todo o modelo será atualizado. Processar todo o modelo

CommitMode é igual a partialBatch. Ele é usado ao fazer uma carga inicial de grandes conjuntos de dados que pode levar horas. Se a operação de atualização falhar depois de confirmar com êxito um ou mais lotes, os lotes confirmados com êxito permanecerão comprometidos (não reverterá lotes confirmados com êxito).

Nota

No momento da escrita, o tamanho do lote é o valor MaxParallelism, mas esse valor pode mudar.

Valores de status

Valor de status Descrição
notStarted Operação ainda não iniciada.
inProgress Operação em curso.
timedOut O tempo limite da operação expirou com base no tempo limite especificado pelo usuário.
cancelled Operação cancelada pelo usuário ou sistema.
failed Falha na operação.
succeeded Operação bem-sucedida.

GET /refreshes/<refreshId>

Para verificar o status de uma operação de atualização, use o verbo GET na ID de atualização. Aqui está um exemplo do corpo de resposta. Se a operação estiver em andamento, inProgress será retornada em status.

{
    "startTime": "2017-12-07T02:06:57.1838734Z",
    "endTime": "2017-12-07T02:07:00.4929675Z",
    "type": "full",
    "status": "succeeded",
    "currentRefreshType": "full",
    "objects": [
        {
            "table": "DimCustomer",
            "partition": "DimCustomer",
            "status": "succeeded"
        },
        {
            "table": "DimDate",
            "partition": "DimDate",
            "status": "succeeded"
        }
    ]
}

GET /refreshes

Para obter uma lista de operações de atualização histórica para um modelo, use o verbo GET na coleção /refreshes. Aqui está um exemplo do corpo de resposta.

Nota

No momento da redação deste artigo, os últimos 30 dias de operações de atualização são armazenados e retornados, mas esse número pode mudar.

[
    {
        "refreshId": "1344a272-7893-4afa-a4b3-3fb87222fdac",
        "startTime": "2017-12-07T02:06:57.1838734Z",
        "endTime": "2017-12-07T02:07:00.4929675Z",
        "status": "succeeded"
    },
    {
        "refreshId": "474fc5a0-3d69-4c5d-adb4-8a846fa5580b",
        "startTime": "2017-12-07T01:05:54.157324Z",
        "endTime": "2017-12-07T01:05:57.353371Z",
        "status": "succeeded"
    }
]

DELETE /refreshes/<refreshId>

Para cancelar uma operação de atualização em andamento, use o verbo DELETE na ID de atualização.

POST /sincronização

Depois de executar operações de atualização, pode ser necessário sincronizar os novos dados com réplicas para expansão da consulta. Para executar uma operação de sincronização para um modelo, use o verbo POST na função /sync. O cabeçalho Location na resposta inclui o ID da operação de sincronização.

GET /sync status

Para verificar o status de uma operação de sincronização, use o verbo GET passando o ID da operação como parâmetro. Aqui está um exemplo do corpo da resposta:

{
    "operationId": "cd5e16c6-6d4e-4347-86a0-762bdf5b4875",
    "database": "AdventureWorks2",
    "UpdatedAt": "2017-12-09T02:44:26.18",
    "StartedAt": "2017-12-09T02:44:20.743",
    "syncstate": 2,
    "details": null
}

Valores para syncstate:

  • 0: Replicação. Os arquivos de banco de dados estão sendo replicados para uma pasta de destino.
  • 1: Reidratação. O banco de dados está sendo reidratado na(s) instância(s) do servidor somente leitura.
  • 2: Concluído. A operação de sincronização foi concluída com êxito.
  • 3: Falhou. A operação de sincronização falhou.
  • 4: Finalização. A operação de sincronização foi concluída, mas está executando etapas de limpeza.

Exemplo de código

Aqui está um exemplo de código C# para você começar, RestApiSample no GitHub.

Para usar o exemplo de código

  1. Clone ou baixe o repo. Abra a solução RestApiSample.
  2. Encontre o cliente da linha . BaseAddress = ... e forneça o URL base.

O exemplo de código usa a autenticação da entidade de serviço.

Service principal (Principal de serviço)

Consulte Criar entidade de serviço - portal do Azure e Adicionar uma entidade de serviço à função de administrador de servidor para obter mais informações sobre como configurar uma entidade de serviço e atribuir as permissões necessárias no Azure AS. Depois de concluir as etapas, conclua as seguintes etapas adicionais:

  1. No exemplo de código, localize string authority = ..., substitua common pelo ID de locatário da sua organização.
  2. Comment/uncomment para que a classe ClientCredential seja usada para instanciar o objeto cred. Certifique-se de que os valores de ID> do Aplicativo e <Chave> do Aplicativo sejam acessados de forma segura ou use a autenticação baseada em certificado para entidades de <serviço.
  3. Execute o exemplo.

Consulte também

Amostras
API REST