Асинхронное обновление с помощью REST API
Используя любой язык программирования, поддерживающий вызовы 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 |
Перечисление | Тип выполняемой обработки. Тип выполняемой обработки зависит от типа команды refresh TMSL: full, clearValues, calculate, dataOnly, automatic или defragment. Тип add не поддерживается. | automatic |
CommitMode |
Перечисление | Определяет, будут объекты зафиксированы в пакетах или только после завершения. Режимы: default, transactional, partialBatch. | transactional |
MaxParallelism |
Int | Это значение определяет максимальное количество потоков, над которыми можно параллельно выполнять команды обработки. Это значение согласуется со свойством MaxParallelism, которое можно задать, используя команду sequence или другими способами. | 10 |
RetryCount |
Int | Указывает число попыток повторить операцию, по исчерпании которого будет определен сбой. | 0 |
Objects |
Массив | Массив объектов для обработки. Для каждого объекта указываются параметр table, если нужно обработать целую таблицу, или параметры table и partition для обработки секции. Если нет указанных объектов, обновляется вся модель. | Обработка целой модели |
Значение CommitMode — partialBatch. Оно используется при начальной загрузке для больших наборов данных, что может занять несколько часов. Если обновление завершится сбоем после успешной фиксации одного или нескольких пакетов, эти пакеты останутся зафиксированными (т. е. для них не будет выполнен откат).
Примечание.
На момент написания статьи требуется, чтобы размер пакета был равен значению 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 Active Directory и субъекта-службы с доступом к ресурсам с помощью портала и Добавление субъекта-службы к роли администратора сервера. Выполнив эти шаги, сделайте дополнительно следующее:
- В примере кода найдите фрагмент string authority = … и замените идентификатор common на код клиента своей организации.
- Закомментируйте или раскомментируйте код, так чтобы класс ClientCredential использовался для создания экземпляра объекта cred. Убедитесь, <что значения идентификатора> приложения и <ключа> приложения доступны безопасно или используют проверку подлинности на основе сертификатов для субъектов-служб.
- Запустите образец.