DataverseClient Класс

Высокоуровневый клиент для операций Microsoft Dataverse.

Этот клиент предоставляет простой стабильный интерфейс для взаимодействия с средами Dataverse через веб-API. Он обрабатывает проверку подлинности с помощью Azure identity и делегирует операции HTTP на внутренний клиент OData.

Ключевые возможности:

  • Операции OData CRUD: создание, чтение, обновление, удаление записей

  • SQL-запросы: выполнение SQL только для чтения с помощью параметра веб-API ?sql

  • Метаданные таблицы: создание, проверка и удаление пользовательских таблиц; создание и удаление столбцов

  • Отправка файлов: отправка файлов в столбцы файлов с поддержкой блокирования

Замечание

Клиент лениво инициализирует внутренний клиент OData при первом использовании, позволяя упрощенное строительство без немедленных сетевых вызовов.

Замечание

Все методы, взаимодействующие с веб-API Dataverse, могут вызываться

HttpError в случае успешного выполнения

HTTP-ответы (например, 401, 403, 404, 429, 500). Отдельный метод

Docstrings документирует только исключения, относящиеся к домену.

Операции организованы в пространства имен:

  • client.records — создание, обновление, удаление и получение записей (одиночные или разбиенные на страницы запросы)

  • client.query — операции запроса и поиска

  • client.tables — управление метаданными таблиц и столбцов

  • client.files — операции отправки файлов

  • client.dataframe — оболочки dataFrame pandas для записи CRUD

  • client.batch — пакетное несколько операций в один HTTP-запрос

Методы бета-версии (client.create, client.query_sqlи т. д.) были удалены в общедоступной версии 1.0. Вызов одного теперь вызывает AttributeError сообщение с именем замены общедоступной версии и команды codemod. Ранее эти вызовы вызвали ошибку AttributeError без указания миграции, поэтому отладка полумигрированного кода была болезненным. См. _REMOVED_BETA_METHODS.

Клиент поддерживает протокол диспетчера контекстов Python для автоматической очистки ресурсов и пула подключений HTTP:

Конструктор

DataverseClient(base_url: str, credential: TokenCredential, config: DataverseConfig | None = None, *, context: OperationContext | None = None)

Параметры

Имя Описание
base_url
Обязательно
str

Например "https://org.crm.dynamics.com", URL-адрес среды Dataverse. Косая черта автоматически удаляется.
credential
Обязательно
TokenCredential

Учетные данные удостоверения Azure для проверки подлинности.
config
DataverseConfig или None

Необязательная конфигурация для языка, времени ожидания и повторных попыток. Если это не указано, значения по умолчанию загружаются из from_env.

Default value: None
context
Обязательно
OperationContext или None

Необязательный объект контекста, определенный вызывающим объектом, добавленным к заголовку исходящего трафика User-Agent для подключаемого модуля или средства attribution. Нельзя использовать вместе с config — передать контекст через DataverseConfig него.

Параметры Keyword-Only

Имя Описание
context
Default value: None

Примеры

Рекомендуется — диспетчер контекстов (включает пул http-подключений):


   from azure.identity import InteractiveBrowserCredential
   from PowerPlatform.Dataverse.client import DataverseClient

   credential = InteractiveBrowserCredential()

   with DataverseClient("https://org.crm.dynamics.com", credential) as client:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
       client.records.update("account", record_id, {"telephone1": "555-0100"})
   # Session closed, caches cleared automatically

Жизненный цикл вручную:


   client = DataverseClient("https://org.crm.dynamics.com", credential)
   try:
       record_id = client.records.create("account", {"name": "Contoso Ltd"})
   finally:
       client.close()

Методы

close

Закройте ресурсы клиента и выпуска.

Закрывает сеанс HTTP (если таковой), очищает внутренние кэши и помечает клиента как закрытый. Безопасно вызывать несколько раз. После закрытия любая операция будет вызываться RuntimeError.

Вызывается автоматически при использовании клиента в качестве диспетчера контекста.

Пример:


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()
flush_cache

Очистка кэшированных метаданных клиента или состояния.

close

Закройте ресурсы клиента и выпуска.

Закрывает сеанс HTTP (если таковой), очищает внутренние кэши и помечает клиента как закрытый. Безопасно вызывать несколько раз. После закрытия любая операция будет вызываться RuntimeError.

Вызывается автоматически при использовании клиента в качестве диспетчера контекста.

Пример:


   client = DataverseClient(base_url, credential)
   try:
       client.records.create("account", {"name": "Contoso"})
   finally:
       client.close()

close() -> None

flush_cache

Очистка кэшированных метаданных клиента или состояния.

flush_cache(kind) -> int

Параметры

Имя Описание
kind
Обязательно
str

Тип кэша для очистки. В настоящее время поддерживаются значения:

  • "picklist": очищает кэш меток выбора, используемый для преобразования меток в целочисленное число

Будущие типы (например "entityset", , "primaryid") могут быть добавлены без нарушения этой подписи.

Возвращаемое значение

Тип Описание
int

Количество удаленных записей кэша.

Примеры

Снимите кэш списка выбора:


   removed = client.flush_cache("picklist")
   print(f"Cleared {removed} cached picklist entries")