Share via

Atualização assíncrona com a API REST

  • Artigo

Ao usar linguagens de programação que sejam compatíveis com chamadas REST, você pode realizar operações de atualização de dados assíncronas em seus modelos de tabela do Azure Analysis Services. Isso inclui a sincronização de réplicas somente leitura para expansão de consulta.

As operações de atualização de dados podem levar algum tempo, dependendo de vários fatores, como volume de dados, nível de otimização que usam partições etc. Essas operações tradicionalmente são invocadas com métodos existentes, como o uso de TOM (modelo de objeto tabular), cmdlets do PowerShell ou TMSL (linguagem de script 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:

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 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 a audiência correta definida como https://*.asazure.windows.net.

  • 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 poderá 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

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

Nome Tipo Descrição Padrão
Type Enum O tipo de processamento a ser executado. Os tipos são alinhados com os tipos de comandos de atualização da TMSL: full, clearValues, calculate, dataOnly, automatic e defragment. Não há suporte para a adição de tipo. automático
CommitMode Enum Determina se os objetos serão confirmados em lotes ou somente na conclusão. 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 é 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 será repetida 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

O CommitMode é igual ao 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 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

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. Ao concluir as etapas, execute as seguintes etapas adicionais:

  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