Compartilhar via

Atualização assíncrona com a API REST

  • Artigo

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

As operações de atualização de dados podem levar algum tempo dependendo de muitos fatores, incluindo volume de dados, nível de otimização usando partições, etc. Tradicionalmente, estas operações têm sido invocadas com métodos existentes, como o uso de TOM (Modelo de Objeto Tabular), cmdlets do PowerShell ou TMSL (Linguagem de Scripts de Modelo Tabular). No entanto, esses métodos geralmente exigem conexões HTTP não confiáveis de execução longa.

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

URL base

A URL base segue este formato:

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

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

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

A URL base para esse nome do servidor será:

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

Ao usar a URL base, os recursos e as operações poderão ser acrescentados com base nos seguintes parâmetros:

Diagrama que mostra a lógica de atualização assíncrona.

  • Qualquer coisa que termine em s é uma coleção.
  • Qualquer coisa que termine com () é uma função.
  • Qualquer outra coisa será 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 do Microsoft Entra ID (OAuth 2) válido no cabeçalho Authorization 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-alvo definido como exatamente https://*.asazure.windows.net. Observe que * não é um espaço reservado ou um curinga, e a audiência deve ter o caractere * como o subdomínio. Não há suporte para públicos-alvo personalizados, como https://customersubdomain.asazure.windows.net. Especificar um público-alvo inválido resulta em falha de autenticação.

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

    Importante

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

POST /refreshes

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 a ID de atualização. O aplicativo cliente pode se desconectar e verificar o status mais tarde, se necessário, porque ele é assíncrono.

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

O corpo pode ser semelhante ao seguinte:

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

Parâmetros

O valor padrão será aplicado se o parâmetro não for especificado.

Nome Tipo Descrição Padrão
Type Enum O tipo de processamento a ser executado. Os tipos são alinhados com os tipos de comando de atualização TMSL: full, clearValues, calculate, dataOnly, automatic e defragment. O tipo add não é compatível. automatic
CommitMode Enum Determina se os objetos são confirmados em lotes ou confirmados somente quando toda a operação é concluída. Os modos incluem: transactional e partialBatch. transactional
MaxParallelism Int Esse valor determina o número máximo de threads nos quais executar comandos de processamento em paralelo. Esse valor é alinhado com a propriedade MaxParallelism, que pode ser definida no comando Sequence da TMSL ou com o uso de outros métodos. 10
RetryCount Int Indica o número de vezes que a operação tenta ser executada novamente antes de falhar. 0
Objects Array Uma matriz de objetos a serem processados. Cada objeto inclui: "table" ao processar a tabela inteira ou "table" e "partition" ao processar uma partição. Se nenhum objeto for especificado, todo o modelo será atualizado. Processar todo o modelo

Especificar partialBatch para CommitMode é útil ao fazer um carregamento 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 confirmados (ela não reverterá lotes confirmadas com êxito).

Observação

No em que esse texto foi escrito, o tamanho do lote era o valor de MaxParallelism, mas esse valor poderá ser alterado.

Valores de status

Valor de status Descrição
notStarted Operação ainda não iniciada.
inProgress Operação em andamento.
timedOut A operação atingiu o tempo limite especificado pelo usuário.
cancelled Operação cancelada pelo usuário ou pelo sistema.
failed Falha na operação.
succeeded Êxito na operação.

GET /refreshes/<refreshId>

Para verificar o status de uma operação de atualização, use o verbo GET na ID da atualização. Aqui está um exemplo do corpo da resposta. Se a operação estiver em andamento, inProgress será retornado no 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 com o histórico das operações de atualização de um modelo, use o verbo GET na coleção /refreshes. Aqui está um exemplo do corpo da resposta.

Observação

No momento em que esse texto foi escrito, os últimos 30 dias de operações de atualização eram armazenados e retornados, mas esse número poderá ser alterado.

[
    {
        "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 da atualização.

POST /sync

Após realizar as operações de atualização, pode ser necessário sincronizar os novos dados com réplicas para expansão de 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 a 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 a ID da operação como um 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
}

Os valores para syncstate:

  • 0: replicando. Os arquivos do banco de dados estão sendo replicados para uma pasta de destino.
  • 1: reidratação. O banco de dados está sendo reidratado em instâncias de servidor somente leitura.
  • 2: concluída. A operação de sincronização foi concluída com êxito.
  • 3: falha. A operação de sincronização falhou.
  • 4: finalizando. 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 em C# para você começar, RestApiSample on GitHub.

Para usar o exemplo de código

  1. Clone ou baixe o repositório. Abra a solução RestApiSample.
  2. Encontre a linha client.BaseAddress = e forneça a URL de base.

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

Entidade de serviço

Confira Criar entidade de serviço – portal do Azure e Adicionar uma entidade de serviço à função de administrador do servidor para obter mais informações, e siga as etapas sobre como configurar uma entidade de serviço e atribuir as permissões necessárias no Azure AS. Em seguida, conclua as seguintes etapas extras:

  1. No código de exemplo, localize string authority = …, substitua common pelo ID de locatário da organização.
  2. Comente/remova a marca de comentário para que a classe ClientCredential seja usada para instanciar o objeto de credencial. Verifique se os valores <App ID> e <App Key> podem ser acessados de forma segura ou use autenticação baseada em certificado para as entidades de serviço.
  3. Execute o exemplo.

Confira também

Amostras
REST API