Share via

Создание или обновление источника данных (предварительная версия REST API)

  • Статья

Применимо к: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Важно!

2023-07-01-Preview (без изменений).

В 2021-04-30-Preview добавлена поддержка управляемых удостоверений для подключений индексатора к другим ресурсам Azure:

  • "учетные данные" принимает идентификатор ресурса Azure в качестве значения при условии, что служба поиска выполняется под управляемым удостоверением, а назначения ролей Azure предоставляют доступ на чтение данных.
  • Identity принимает управляемое удостоверение, назначаемое пользователем. Это свойство является первым уровнем для подключений к данным. Он также находится в разделе encryptionKey для получения ключа, управляемого клиентом, в Azure Key Vault.
  • Файлы Azure поддержка доступна в предварительной версии. Используйте предварительную версию API для индексирования из этого источника данных.

30.06.2020 добавляется:

  • "dataDeletionDetectionPolicy" принимает "NativeBlobSoftDeleteDeletionDetectionPolicy" для индексаторов BLOB-объектов.
  • База данных Azure для MySQL поддержка доступна в предварительной версии. Используйте предварительную версию API для индексирования из этого источника данных.
  • Поддержка API MongoDB и Api Gremlin для Cosmos DB доступна в предварительной версии. Используйте предварительную версию API для индексирования из этого источника данных.

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

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

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. Если объект не существует, он создается. Если он уже существует, он перезаписывается с помощью нового определения.

Примечание

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

Параметры URI

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

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

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

Поля Описание
Content-Type Обязательный. Для этого заголовка необходимо задать значение application/json
api-key Необязательно, если вы используете роли Azure и в запросе предоставляется маркер носителя, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса к службе поиска. Запросы на создание должны содержать 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" : (required) { "name" : "Name of the table, collection, or blob container you wish to index" },  
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "identity": (optional) {Sets the Resource ID of a managed identity. See below for details },
    "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.",
      "identity": "(Resource ID of a user-assigned managed identity, used for connecting to key vault)",
      "accessCredentials": (Credentials for connecting to key vault. Omit if using a managed identity) {
        "applicationId": "Azure AD Application ID that has access permissions to the key vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

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

Свойство Описание
name Обязательный. Имя источника данных. Имя источника данных должно содержать только строчные буквы, цифры или дефисы, не может начинаться или заканчиваться дефисами, а его длина ограничена 128 символами.
description Необязательное описание.
тип Обязательный. Должен быть одним из поддерживаемых типов источников данных:
adlsgen2
для Azure Data Lake Storage 2-го поколения
azureblob для Хранилище BLOB-объектов Azure
azurefiles для хранилища
azuresql файлов Azure для базы данных
azuretable Azure SQL для таблицы Azure. Хранилище
cosmosdb для API SQL Azure Cosmos DB, API MongoDB, API
mysql Gremlin для База данных Azure для MySQL
credentials Обязательный элемент. Содержит connectionString свойство, указывающее способ подключения.
контейнер Обязательный. Указывает контейнер, коллекцию, таблицу или представление, содержащее индексированные данные.
dataChangeDetectionPolicy Необязательный элемент. Указывает механизм, предоставляемый платформой данных для идентификации измененных элементов данных.
dataDeletionDetectionPolicy Необязательный элемент. Определяет, как платформа данных удаляет данные.
encryptionKey Необязательный элемент. Используется для дополнительного шифрования учетных данных источника данных с помощью управляемых клиентом ключей шифрования (CMK) в Azure Key Vault. Доступно для оплачиваемых служб поиска, созданных в 01.01.2019 или позже.
disabled Необязательный элемент. Логическое значение, указывающее, создан ли индексатор в отключенном состоянии, что препятствует его немедленному запуску. Значение по умолчанию: false.
удостоверение Необязательный элемент. Он содержит userAssignedIdentity тип #Microsoft.Azure.Search.DataUserAssignedIdentity и указывает назначаемое пользователем управляемое удостоверение внешнего ресурса. Это свойство зависит credentials от наличия строка подключения в правильном формате (идентификатор ресурса) для подключений управляемых удостоверений для каждого типа источника данных.

identity Если свойство имеет значение NULL, подключение к идентификатору ресурса осуществляется с помощью управляемого системой свойства .

Если это свойство присвоено типу #Microsoft.Azure.Search.DataNoneIdentity, все явно указанные ранее удостоверения очищаются.

Ответ

Для успешного запроса: код состояния "201 Создан ресурс", если источник данных был создан, и "204 Нет содержимого", если был обновлен существующий источник данных.

Примеры

Пример: роли Azure и управляемое удостоверение, назначаемое системой

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

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
  }

Пример: роли Azure и управляемое удостоверение, назначаемое пользователем (предварительная версия)

В этом примере демонстрируется подключение Azure AD с проверкой подлинности для службы поиска, которая имеет управляемое удостоверение, назначаемое пользователем.

{
    "name": "azure-blob-ds",
    "description": "a description of the blob data",
    "type": "azureblob",
    "subtype": null,
    "credentials": {
      "connectionString": "ResourceId=/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.Storage/storageAccounts/[storage account name]/;"
    },
    "container": {
      "name": "mycontainer"
    },
    "dataChangeDetectionPolicy": null,
    "dataDeletionDetectionPolicy": null,
    "identity": {
      "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
      "userAssignedIdentity": "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[user identity name]"
    }
  }

Пример: 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 identity) {
        "applicationId": "Azure Active Directory Application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the specified Azure AD application)"}
      }
}

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

В этом примере пропускается accessCredentials. Для ресурса, которому назначено управляемое удостоверение, назначаемое пользователем , можно указать удостоверение в encryptionKey и получить ключ с помощью этого удостоверения и назначений ролей Azure.

{
    "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",
      "identity": {
        "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
        "userAssignedIdentity": "/subscriptions/00000000-0000-0000-0000-000000000000/resourceGroups/contoso-rg/providers/Microsoft.ManagedIdentity/userAssignedIdentities/contoso-identity"
        }
    }
}

Определения

Ссылка Описание
container Указывает контейнер, коллекцию, таблицу или представление, содержащее индексированные данные.
credentials Содержит connectionString свойство, указывающее, как индексатор подключается к ресурсу Azure.
dataChangeDetectionPolicy Указывает механизм, предоставляемый платформой данных для идентификации измененных данных.
dataDeletionDetectionPolicy Задает механизм обнаружения удаленных данных.
encryptionKey Настраивает подключение к Azure Key Vault для шифрования, управляемого клиентом.

контейнер

Указывает контейнер, коллекцию, таблицу или представление, содержащее индексированные данные.

attribute Описание
name Обязательный. Для Azure Cosmos DB указывает коллекцию API SQL. Для Хранилище BLOB-объектов Azure указывает контейнер хранилища. Для Azure SQL указывает таблицу или представление. Можно использовать имена с указанием через схему, такие как [dbo].[mytable]. Для хранилища таблиц Azure указывает имя таблицы.
query Необязательный элемент. Для Azure Cosmos DB позволяет указать запрос, который преобразует произвольный макет документа JSON в плоскую схему, которую может индексировать служба поиска Azure AI. Для Хранилище BLOB-объектов Azure позволяет указать виртуальную папку в контейнере больших двоичных объектов. Например, в пути к большому двоичному объекту mycontainer/documents/blob.pdf в качестве виртуальной папки можно использовать documents. Для хранилища таблиц Azure позволяет указать запрос, который фильтрует импортируемый набор строк. Для Azure SQL запрос не поддерживается (вместо этого используйте представления).

credentials

Содержит свойство connectionString, указывающее, как индексатор подключается к ресурсу Azure.

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

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

Для базы данных 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.

Если вы используете управляемое удостоверение для проверки подлинности, вы можете опустить учетные данные для подключения.

Для подключений, которые проходят проверку подлинности с помощью управляемого удостоверения, строка подключения указывает идентификатор ресурса Azure (см. эти ссылки для формата строка подключения: Служба хранилища Azure, Cosmos DB, База данных SQL).

Назначения ролей, ограниченные внешним источником данных, определяют, может ли индексатор подключаться, и служба поиска должна быть настроена для запуска в качестве доверенной службы в Azure Active Directory.

Если также указано свойство identity, подключение выполняется с помощью управляемого удостоверения, назначаемого пользователем службы поиска, которое предоставляется свойством identity. В противном случае, если "удостоверение" не указано или имеет значение NULL, подключение осуществляется через управляемое системой удостоверение.

dataChangeDetectionPolicy

Указывает механизм, предоставляемый платформой данных для идентификации измененных данных. Поддерживаемые политики зависят от типа источника данных.

attribute Описание
dataChangeDetectionPolicy Необязательный элемент. Допустимые политики включают HighWatermarkChangeDetectionPolicy или SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy зависит от существующего столбца или свойства, которое обновляется вместе с другими обновлениями (все вставки приводят к обновлению столбца подложки), и изменение значения выше.

SqlIntegratedChangeDetectionPolicyиспользуется для ссылки на собственные функции обнаружения изменений в SQL Server. Эту политику можно использовать только с таблицами; Его нельзя использовать с представлениями. Перед использованием этой политики вам потребуется включить отслеживание изменений для используемой таблицы. Инструкции см. в разделе Включение и отключение отслеживания изменений.
highWaterMarkColumnName Обязательно для HighWatermarkChangeDetectionPolicy. Для Cosmos DB столбец должен быть свойством _ts . Для Azure SQL рекомендуется использовать индексированные столбцыrowversion. Для службы хранилища Azure обнаружение изменений встроено с помощью значений lastModified, что устраняет необходимость в настройке dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Указывает механизм, предоставляемый платформой данных для идентификации удаленных данных. Поддерживаемые политики зависят от типа источника данных.

attribute Описание
dataDeletionDetectionPolicy Необязательный элемент. Допустимые значения: SoftDeleteColumnDeletionDetectionPolicy или NativeBlobSoftDeleteDeletionDetectionPolicy (см . раздел Обратимое удаление большого двоичного объекта в собственном коде (предварительная версия)).

В настоящее время единственной общедоступной политикой являетсяSoftDeleteColumnDeletionDetectionPolicy , которая определяет удаленные элементы на основе значения столбца или свойства обратимого удаления в источнике данных.

softDeleteColumnName" Обязательный. Имя столбца в источнике данных, указывающее состояние удаления строки. Например, можно создать столбец с именем IsDeleted. Поддерживаются только столбцы, имеющие строковые, целочисленные или логические значения.
softDeleteMarkerValue Обязательный. Значение столбца обратимого удаления. Значение, используемое в качестве softDeleteMarkerValue , должно быть строкой, даже если соответствующий столбец содержит целые или логические значения. Например, если в источнике данных отображается значение 1, используйте "1" в softDeleteMarkerValueкачестве значения . Если индексатор считывает это значение из столбца обратимого удаления, он удаляет соответствующий поисковый документ из индекса поиска.

encryptionKey

Настраивает подключение к Azure Key Vault для дополнительных ключей шифрования, управляемых клиентом (CMK). Шифрование с помощью ключей, управляемых клиентом, недоступно для бесплатных служб. Для оплачиваемых служб они доступны только для служб поиска, созданных в 01.01.2019 или позже.

Подключение к хранилищу ключей должно пройти проверку подлинности. Для этой цели можно использовать accessCredentials или управляемое удостоверение.

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

attribute Описание
keyVaultKeyName Обязательный. Имя ключа Key Vault Azure, используемого для шифрования.
keyVaultKeyVersion Обязательный. Версия ключа Key Vault Azure.
keyVaultUri Обязательный. URI azure Key Vault (также называется DNS-именем), предоставляющий ключ. Пример URI: https://my-keyvault-name.vault.azure.net.
accessCredentials Опустить, если вы используете управляемое удостоверение. В противном случае свойства accessCredentials включают applicationId (идентификатор приложения Azure Active Directory с разрешениями на доступ к указанному Key Vault Azure) и applicationSecret (ключ проверки подлинности указанного приложения Azure AD).
удостоверение Необязательный, если вы не используете управляемое удостоверение, назначаемое пользователем, для подключения службы поиска к Azure Key Vault. Формат — "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

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