Асинхронное обновление с помощью REST API

Статья
06/26/2024

Используя любой язык программирования, поддерживающий вызовы REST, вы можете выполнять асинхронные операции обновления данных в табличных моделях Служб Azure Analysis Services, включая синхронизацию реплик только для чтения для масштабирования запросов.

Операции обновления данных могут занять некоторое время в зависимости от многих факторов, включая объем данных, уровень оптимизации с помощью секций и т. д. Традиционно эти операции вызываются с помощью существующих методов, таких как использование TOM (табличной объектной модели), командлетов PowerShell или TMSL (язык скриптов табличных моделей). Но для использования этих методов может понадобиться применить ненадежные длительные HTTP-подключения.

REST API для Azure Analysis Services позволяет выполнять обновления данных асинхронно. REST API устраняет необходимость в длительных подключениях через клиентские приложения. Кроме того, здесь предусмотрены другие возможности, обеспечивающие надежность работы, такие как выполнение повторных попыток и пакетных фиксаций.

Базовый URL-адрес

У базового URL-адреса должен быть такой формат:

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

Например, рассмотрим модель с именем AdventureWorks на сервере с именем myserver, расположенном в регионе Azure на западе США. Тогда у сервера будет такое имя:

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

Базовый URL-адрес для сервера с этим именем будет таким:

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

Базовый URL-адрес можно использовать, чтобы добавлять ресурсы и операции на основе следующих параметров:

Схема, демонстрирующая асинхронную логику обновления.

Все, что заканчивается на s — коллекции.
Все, что заканчивается на () — функции.
Все остальное — это ресурсы или объекты.

Например, вы можете выполнить обновление, применив команду POST к коллекции refreshes:

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

Проверка подлинности

Все вызовы должны проходить проверку подлинности с помощью допустимого маркера Microsoft Entra ID (OAuth 2) в заголовке авторизации и должны соответствовать следующим требованиям:

Токен должен быть пользовательским маркером или субъектом-службой приложения.
Маркер должен иметь точное значение https://*.asazure.windows.netаудитории. Обратите внимание, что * это не заполнитель или подстановочный знак, а аудитория должна иметь * символ в качестве поддомена. Указание недопустимой аудитории приводит к сбою проверки подлинности.
У пользователя или приложения должно быть достаточно разрешений для сервера или модели, чтобы выполнять запрашиваемые вызовы. Уровень разрешений определяется по ролям в модели или группе администраторов на сервере.

Внимание

Сейчас требуются разрешения роли администратора сервера.

POST для /refreshes

Выполните обновление, применив команду POST к коллекции /refreshes, чтобы добавить в нее новый элемент. Под заголовком Location в ответе будет указан идентификатор обновления. Клиентское приложение может отключить и проверить состояние позже, так как это асинхронно.

Для одной модели можно выполнить только одну операцию обновления. Если во время одной операции обновления запустить вторую, возвращается конфликт с кодом состояния HTTP 409.

Текст должен выглядеть примерно так:

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

Параметры

Значение по умолчанию применяется, если параметр не указан.

Имя.	Тип	Описание	По умолч.
`Type`	Перечисление	Тип выполняемой обработки. Типы соответствуют типам команд обновления TMSL: `full`, , `clearValues`, `calculatedataOnly`и `automaticdefragment`. `add` тип не поддерживается.	`automatic`
`CommitMode`	Перечисление	Определяет, фиксируются ли объекты в пакетах или фиксируются только после завершения всей операции. Режимы включают: `transactional`, `partialBatch`.	`transactional`
`MaxParallelism`	Int	Это значение определяет максимальное количество потоков, над которыми можно параллельно выполнять команды обработки. Это значение согласуется со свойством MaxParallelism, которое можно задать, используя команду sequence или другими способами.	10
`RetryCount`	Int	Указывает количество повторных попыток операции перед сбоем.	0
`Objects`	Массив	Массив объектов для обработки. Для каждого объекта указываются параметр table, если нужно обработать целую таблицу, или параметры table и partition для обработки секции. Если нет указанных объектов, обновляется вся модель.	Обработка целой модели

Указание partialBatchCommitMode полезно при начальной загрузке больших наборов данных, которые могут занять несколько часов. Если обновление завершится сбоем после успешной фиксации одного или нескольких пакетов, эти пакеты останутся зафиксированными (т. е. для них не будет выполнен откат).

Примечание.

На момент написания статьи требуется, чтобы размер пакета был равен значению MaxParallelism, но это могло измениться.

Индикаторы состояния

Значение состояния	Description
`notStarted`	Операция еще не запущена.
`inProgress`	Выполняется операция.
`timedOut`	Время ожидания операции истекло на основании указанного пользователем времени ожидания.
`cancelled`	Операция отменена пользователем или системой.
`failed`	Ошибка при выполнении операции.
`succeeded`	Операция выполнена успешно.

GET /refreshes/<refreshId>

Чтобы проверить состояние обновления, используйте команду GET с идентификатором обновления. Ниже приведен пример текста ответа. Если операция выполняется, inProgress возвращается в статусе.

{
    "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

Чтобы получить список последних операций обновления для модели, примените команду GET к коллекции /refreshes. Ниже приведен пример текста ответа.

Примечание.

На момент написания этой статьи предусматривается, что сохраняются и возвращаются операции обновления за последние 30 дней, но это могло измениться.

[
    {
        "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>

Чтобы отменить выполняющееся обновление, примените команду DELETE к идентификатору обновления.

POST для /sync

После выполнения операций обновления может потребоваться синхронизация новых данных с репликами для горизонтального масштабирования запросов. Чтобы выполнить операцию синхронизации для модели, используйте команду POST для функции /sync. Под заголовком Location в ответе будет указан идентификатор операции.

GET для состояния /sync

Чтобы проверить состояние синхронизации, используйте команду GET, передав в качестве параметра идентификатор операции. Вот пример текста ответа:

{
    "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
}

Значения для syncstate:

0 — репликация. Файлы базы данных реплицируются в целевую папку.
1 — восстановление. База данных восстанавливается на серверных экземплярах только для чтения.
2 — завершено. Синхронизация успешно выполнена.
3 — сбой операции.
4 — финализация. Синхронизация завершена, но еще выполняется очистка.

Пример кода

Здесь приведен пример кода C# для начала работы: RestApiSample на GitHub.

Как пользоваться примером кода

Клонируйте или скачайте репозиторий. Откройте решение RestApiSample.
Найдите клиент строки . BaseAddress = ... и укажите базовый URL-адрес.

В примере кода используется аутентификация субъекта-службы.

Субъект-служба

Дополнительные сведения о настройке субъекта-службы и назначении необходимых разрешений в Azure AS см. в статье "Создание субъекта-службы" портал Azure и добавление субъекта-службы в роль администратора сервера. Затем выполните следующие дополнительные действия:

В примере кода найдите фрагмент string authority = … и замените идентификатор common на код клиента своей организации.
Закомментируйте или раскомментируйте код, так чтобы класс ClientCredential использовался для создания экземпляра объекта cred. Убедитесь, <что значения идентификатора> приложения и <ключа> приложения доступны безопасно или используют проверку подлинности на основе сертификатов для субъектов-служб.
Запустите образец.

См. также

Примеры
REST API

Поделиться через