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

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

  • Статья

применимо к: 2023-07-01-Preview. Эта версия больше не поддерживается. немедленное обновление до более новой версии.

Важный

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

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

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

2020-06-30-Preview добавляет:

  • dataDeletionDetectionPolicy принимает "NativeBlobSoftDeleteDeletionDetectionPolicy" для индексаторов BLOB-объектов.
  • поддержка базы данных Azure для MySQL доступна в предварительной версии. Используйте API предварительной версии для индексирования из этого источника данных.
  • API MongoDB Cosmos DB и API Gremlin поддерживаются предварительной версией. Используйте 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 требуется для всех запросов службы. Если объект не существует, он создается. Если он уже существует, он перезаписывается с помощью нового определения.

Заметка

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

Параметры URI

Параметр Описание
Имя службы Обязательно. Задайте для этого уникальное, определяемое пользователем имя службы поиска.
Имя источника данных Обязательный код ресурса (URI) при использовании PUT. Имя должно быть нижним регистром, начинаться с буквы или числа, не иметь косой черты или точки, а также быть менее 128 символов. После запуска имени с буквой или номером остальная часть имени может включать любые буквы, цифры и дефисы, если дефисы не являются последовательными.
версия API Обязательно. Дополнительные версии API см. в версиях API.

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

В следующей таблице описаны обязательные и необязательные заголовки запросов.

Поля Описание
Тип контента Обязательно. Задайте для этого значение application/json
api-key Необязательно, если вы используете роли Azure и маркер носителя предоставляется в запросе, в противном случае требуется ключ. Ключ API — это уникальная, созданная системой строка, которая проверяет подлинность запроса в службе поиска. Запросы на создание должны содержать заголовок api-key, заданный для ключа администратора (в отличие от ключа запроса). Дополнительные сведения см. в статье Connect to Azure AI Search using key authentication.

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

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

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

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

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

Свойство Описание
имя Обязательно. Имя источника данных. Имя источника данных должно содержать только строчные буквы, цифры или дефисы, не может начинаться или заканчиваться дефисом и ограничен 128 символами.
описание Необязательное описание.
тип Обязательно. Должен быть одним из поддерживаемых типов источников данных:

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

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

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

Ответ

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

Примеры

пример: роли 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]"
    }
  }

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

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

пример: SQL 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.SqlIntegratedChangeTrackingPolicy" }
}

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

Помните, что свойства для обнаружения удаления : 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"
        }
    }
}

Определения

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

контейнер

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

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

верительные грамоты

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

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

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

для базы данных SQL Azure это обычная строка подключения 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

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

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

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

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

dataDeletionDetectionPolicy

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

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

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

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

encryptionKey

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

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

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

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

См. также