Создание источника данных (REST API поиска ИИ Azure)

  • Статья

В поиске ИИ Azure источник данных используется с индексаторами, предоставляя сведения о подключении по запросу или запланированному обновлению данных целевого индекса, извлекая данные из поддерживаемых источников данных Azure.

Для запроса можно использовать POST или PUT. Для любого из них документ JSON в тексте запроса предоставляет определение объекта.

POST https://[service name].search.windows.net/datasources?api-version=[api-version]  
    Content-Type: application/json  
    api-key: [admin key]

Кроме того, можно использовать PUT и указать имя в URI.

PUT https://[service name].search.windows.net/datasources/[data source name]?api-version=[api-version]
    Content-Type: application/json  
    api-key: [admin key]

Все запросы к службе отправляются по протоколу HTTPS. Если объект не существует, он создается. Если он уже существует, он обновляется до нового определения.

Примечание

Максимальное количество индексов, которое можно создать, зависит от ценового уровня. Дополнительные сведения см. в статье Ограничения службы.

Параметры URI

Параметр Описание
имя службы Обязательный. Задайте уникальное, определяемое пользователем имя службы поиска.
имя источника данных Требуется для URI, если используется PUT. Имя должно быть строчным, начинаться с буквы или цифры, не содержать косых черт или точек и содержать менее 128 символов. Имя должно начинаться с буквы или цифры, но остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
api-version Обязательный. Список поддерживаемых версий см. в разделе Версии API.

Заголовки запросов

Таблица ниже содержит обязательные и необязательные заголовки запроса.

Поля Описание
Content-Type Обязательный. Для этого заголовка необходимо задать значение application/json
api-key Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Запросы на создание должны включать заголовок, заданный api-key для ключа администратора (в отличие от ключа запроса). Дополнительные сведения см. в статье Подключение к поиску ИИ Azure с помощью проверки подлинности по ключу .

Текст запроса

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

Следующий код JSON представляет собой общее представление main частей определения.

{   
    "name" : (optional on PUT; required on POST) "Name of the data source",  
    "description" : (optional) "Anything you want, or nothing at all",  
    "type" : (required) "Must be a supported data source",
    "credentials" : (required) { "connectionString" : "Connection string for your data source" },
    "container": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

Запрос содержит следующие свойства.

Свойство Описание
name Обязательный. Имя источника данных. Имя источника данных должно содержать только строчные буквы, цифры или дефисы, не может начинаться или заканчиваться дефисами и может содержать только 128 символов.
description Необязательное описание.
тип Обязательный. Должен быть одним из поддерживаемых типов источников данных:
azuresql
для базы данных Azure SQL, Управляемый экземпляр SQL Azure или экземпляра SQL Server, работающего на виртуальной машине
cosmosdb Azure для Azure Cosmos DB для NoSQL, Azure Cosmos DB для MongoDB (предварительная версия) или Azure Cosmos DB для Apache Gremlin (предварительная версия)
azureblob for Хранилище BLOB-объектов Azure
adlsgen2 for Azure Data Lake Storage 2-го поколения
azuretable for Azure Table Storage
azurefile for Файлы Azure (preview)
mysql for База данных Azure для MySQL (предварительная версия)
sharepoint для SharePoint в Microsoft 365 (предварительная версия)
credentials Обязательный. Он содержит connectionString свойство , указывающее строка подключения для источника данных. Формат строка подключения зависит от типа источника данных.

Для базы данных Azure SQL это обычная SQL Server строка подключения. Если вы используете портал Azure для получения строка подключения, выберите ADO.NET connection string параметр .

Для Azure Cosmos DB строка подключения должны иметь следующий формат: "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]". Все значения являются обязательными. Эти значения можно найти на портале Azure.

Для Хранилище BLOB-объектов Azure форматы строка подключения определяются в разделе Учетные данные статьи Настройка индексирования BLOB-объектов в поиске ИИ Azure.

Служба хранилища Azure, база данных Azure SQL и Azure Cosmos DB также поддерживают управляемое удостоверение строка подключения, не включающее ключ учетной записи в строка подключения. Чтобы использовать формат управляемого удостоверения строка подключения, следуйте инструкциям в статье Настройка подключения индексатора к источнику данных с помощью управляемого удостоверения.

При обновлении источника данных строка подключения не требуется. Значения <unchanged> или <redacted> могут использоваться вместо фактического строка подключения.
контейнер Обязательный. Указывает данные для индексирования с помощью name свойствname

(обязательно) и query (необязательно): для
Azure SQL указывает таблицу или представление. Можно использовать имена с указанием через схему, такие как [dbo].[mytable].
Для Azure Cosmos DB указывает коллекцию API SQL.
Для Хранилище BLOB-объектов Azure указывает контейнер хранилища.
Для хранилища таблиц Azure указывает имя таблицы.

query:
для Azure Cosmos DB позволяет указать запрос, который преобразует произвольный макет документа JSON в плоскую схему, которую поиск ИИ Azure может индексировать.
Для Хранилище BLOB-объектов Azure позволяет указать виртуальную папку в контейнере BLOB-объектов. Например, в пути к большому двоичному объекту mycontainer/documents/blob.pdf в качестве виртуальной папки можно использовать documents.
Для хранилища таблиц Azure позволяет указать запрос, который фильтрует набор импортируемых строк.
Для Azure SQL запросы не поддерживаются. Вместо этого используйте представления.
dataChangeDetectionPolicy Необязательный элемент. Используется для идентификации измененных элементов данных. Поддерживаемые политики зависят от типа источника данных. Допустимыми политиками являются политика обнаружения изменений с высоким уровнем подложки и интегрированная политика обнаружения изменений SQL.

Политика обнаружения изменений высокого предела зависит от существующего столбца или свойства, которое обновляется вместе с другими обновлениями (все вставки приводят к обновлению столбца подложки), и изменение значения выше. Для источников данных Cosmos DB необходимо использовать _ts свойство . Для Azure SQL индексированные rowversion столбцы являются идеальным кандидатом для использования с политикой высокой отметки воды. Для службы хранилища Azure обнаружение изменений встроено с использованием значений lastModified, что избавляет от необходимости задавать dataChangeDetectionPolicy для хранилища BLOB-объектов или таблиц.

Интегрированная политика обнаружения изменений SQL используется для ссылки на собственные функции обнаружения изменений в SQL Server. Эту политику можно использовать только с таблицами; Его нельзя использовать с представлениями. Перед использованием этой политики вам потребуется включить отслеживание изменений для используемой таблицы. Инструкции см. в разделе Включение и отключение отслеживания изменений. Дополнительные сведения о поддержке обнаружения изменений в индексаторе см. в разделе Подключение к содержимому и индексирование Azure SQL.
dataDeletionDetectionPolicy Необязательный элемент. Используется для идентификации удаленных элементов данных. В настоящее время единственной поддерживаемой политикой является политика обратимого удаления, которая идентифицирует удаленные элементы на основе значения столбца или свойства обратимого удаления в источнике данных.

Поддерживаются только столбцы со строковыми, целыми или логическими значениями. Значение, используемое в качестве softDeleteMarkerValue , должно быть строкой, даже если соответствующий столбец содержит целые или логические значения. Например, если в источнике данных отображается значение 1, используйте "1" в softDeleteMarkerValueкачестве значения .
encryptionKey Необязательный элемент. Используется для шифрования неактивного источника данных с помощью собственных ключей, управляемых в Key Vault Azure. Доступно для оплачиваемых служб поиска, созданных в 01.01.2019 или позже.

Раздел encryptionKey содержит определяемые keyVaultKeyName пользователем (обязательные), системные keyVaultKeyVersion (обязательные) и keyVaultUri предоставляющие ключ (обязательный, также называемый DNS-именем). Пример URI может иметь значение "https://my-keyvault-name.vault.azure.net".

При необходимости можно указать accessCredentials , используете ли вы не управляемое системное удостоверение. accessCredentials Свойства включают applicationId (Microsoft Entra ID идентификатор приложения, которому предоставлены разрешения на доступ к указанному Key Vault Azure) и applicationSecret (ключ проверки подлинности зарегистрированного приложения). Пример в следующем разделе иллюстрирует синтаксис.

Ответ

Для успешного запроса: "201 — Создан ресурс".

Примеры

Пример: Azure SQL с обнаружением изменений (политика обнаружения изменений с высоким уровнем подложки)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.HighWaterMarkChangeDetectionPolicy", "highWaterMarkColumnName" : "RowVersion" }
}

Пример: Azure SQL с обнаружением изменений (интегрированная политика Отслеживание изменений SQL)

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },  
    "dataChangeDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SqlIntegratedChangeTrackingPolicy" }
}

Пример: Azure SQL с обнаружением изменений с обнаружением удаления

Помните, что свойства для обнаружения удаления: softDeleteColumnName и softDeleteMarkerValue.

{   
    "name" : "asqldatasource",  
    "description" : "a description",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" },   
    "dataDeletionDetectionPolicy" : { "@odata.type" : "#Microsoft.Azure.Search.SoftDeleteColumnDeletionDetectionPolicy", "softDeleteColumnName" : "IsDeleted", "softDeleteMarkerValue" : "true" }  
}

Пример. Источник данных только с обязательными свойствами

Необязательные свойства, связанные с обнаружением изменений и удаления, можно опустить, если планируется использовать источник данных только для одноразового копирования данных:

{   
    "name" : "asqldatasource",  
    "description" : "anything you want, or nothing at all",  
    "type" : "azuresql",  
    "credentials" : { "connectionString" : "Server=tcp:....database.windows.net,1433;Database=...;User ID=...;Password=...;Trusted_Connection=False;Encrypt=True;Connection Timeout=30;" },  
    "container" : { "name" : "sometable" }  
}

Пример. Пропуск учетных данных

Если вы планируете обновить источник данных, учетные данные не требуются. Значения <unchanged> или <redacted> могут использоваться вместо строка подключения.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
}

Пример. Ключи шифрования

Ключи шифрования — это управляемые клиентом ключи, используемые для дополнительного шифрования. Дополнительные сведения см. в статье Шифрование с помощью ключей, управляемых клиентом, в Azure Key Vault.

{
    "name" : "adatasource",
    "description": "a description",
    "type": "azuresql",
    "credentials": { "connectionString": "<unchanged>" },
    "container" : { "name": "sometable" }
    "encryptionKey": (optional) { 
      "keyVaultKeyName": "Name of the Azure Key Vault key used for encryption",
      "keyVaultKeyVersion": "Version of the Azure Key Vault key",
      "keyVaultUri": "URI of Azure Key Vault, also referred to as DNS name, that provides the key. An example URI might be https://my-keyvault-name.vault.azure.net",
      "accessCredentials": (optional, only if not using managed system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

См. также раздел