Partilhar via

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, incluindo 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 muitos fatores, incluindo volume de dados, nível de otimização usando partições, etc. Tradicionalmente, essas operações têm sido 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:

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 é 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 tem de ter a audiência definida exatamente como https://*.asazure.windows.net. Observe que * não é um espaço reservado ou um curinga, e o público deve ter o * caractere como subdomínio. Não há suporte para públicos personalizados, como https://customersubdomain.asazure.windows.net, . Especificar uma audiência inválida resulta em falha de autenticação.

  • 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

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

Nome Tipo Description Predefinido
Type Enumeração O tipo de processamento a ser executado. Os tipos estão alinhados com os tipos de comando de atualização TMSL: full, clearValues, calculate, dataOnly, automatic, e defragment. add type não é suportado. automatic
CommitMode Enumeração Determina se os objetos são confirmados em lotes ou confirmados somente quando toda a operação é concluída. Os modos incluem: transactional, partialBatch. transactional
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 tenta novamente 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

Especificar partialBatch para CommitMode é útil 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 Description
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 as 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 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 exemplo de código, localize a autoridade da cadeia de caracteres = ..., substitua comum pelo ID do 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