Creación de un origen de datos (API rest de Azure AI Search)

Artículo
11/13/2023

En Azure AI Search, se usa un origen de datos con indexadores, lo que proporciona la información de conexión para la actualización de datos a petición o programada de un índice de destino, que extrae datos de orígenes de datos de Azure compatibles.

Puede usar POST o PUT en la solicitud. Para cualquiera de ellos, el documento JSON del cuerpo de la solicitud proporciona la definición de objeto.

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

Como alternativa, puede usar PUT y especificar el nombre en el 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 es necesario para todas las solicitudes de servicio. Si el objeto no existe, se crea. Si ya existe, se actualiza a la nueva definición.

Nota

El número máximo de índices que se pueden crear varía según el nivel de precios. Para más información, consulte los límites del servicio.

Parámetros de identificador URI

Parámetro	Descripción
nombre del servicio	Necesario. Establézcalo en el nombre único definido por el usuario del servicio de búsqueda.
nombre del origen de datos	Obligatorio en el URI si usa PUT. El nombre debe estar en minúsculas, comenzar con una letra o un número, no tener barras diagonales ni puntos y tener menos de 128 caracteres. El nombre debe comenzar con una letra o un número, pero el resto del nombre puede incluir cualquier letra, número y guiones, siempre y cuando los guiones no sean consecutivos.
api-version	Necesario. Consulte Versiones de API para obtener una lista de las versiones admitidas.

Encabezados de solicitud

En la siguiente tabla se describen los encabezados de solicitud obligatorios y opcionales.

Campos	Descripción
Content-Type	Necesario. Establézcalo en `application/json`
api-key	Opcional si usa roles de Azure y se proporciona un token de portador en la solicitud; de lo contrario, se requiere una clave. Las solicitudes de creación deben incluir un `api-key` encabezado establecido en la clave de administración (en lugar de una clave de consulta). Consulte Conexión a Azure AI Search mediante la autenticación de claves para más información.

Cuerpo de la solicitud

El cuerpo de la solicitud contiene una definición de origen de datos, que incluye el tipo de origen de datos, las credenciales para leer los datos, así como políticas de detección de cambios en los datos opcionales y de detección de eliminación de datos que se usan para identificar de forma eficaz datos cambiados o eliminados en el origen de datos cuando se usan con un indexador programado periódicamente.

El siguiente JSON es una representación de alto nivel de las partes principales de la definición.

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

La solicitud contiene las siguientes propiedades:

Propiedad	Descripción
name	Necesario. El nombre del origen de datos. Un nombre de origen de datos solo debe contener letras minúsculas, dígitos o guiones, no puede empezar ni terminar con guiones y está limitado a 128 caracteres.
description	Descripción opcional.
type	Necesario. Debe ser uno de los tipos de origen de datos admitidos: `azuresql` para Azure SQL Database, Azure SQL Managed Instance o SQL Server instancia que se ejecuta en una máquina virtual `cosmosdb` de Azure para Azure Cosmos DB para NoSQL, Azure Cosmos DB para MongoDB (versión preliminar) o Azure Cosmos DB para Apache Gremlin (versión preliminar) `azureblob` for Azure Blob Storage `adlsgen2` for Azure Data Lake Storage Gen2 `azuretable` for Azure Table Storage `azurefile` for Azure Files (preview) `mysql` for Azure Database for MySQL ( preview) `sharepoint` para SharePoint en Microsoft 365(versión preliminar)
credentials	Necesario. Contiene una `connectionString` propiedad que especifica la cadena de conexión para el origen de datos. El formato del cadena de conexión depende del tipo de origen de datos: para Azure SQL Database, este es el SQL Server cadena de conexión habitual. Si usa Azure Portal para recuperar el cadena de conexión, elija la `ADO.NET connection string` opción . Para Azure Cosmos DB, el cadena de conexión debe tener el siguiente formato: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Todos los valores son obligatorios. Puede encontrarlos en Azure Portal. Para Azure Blob Storage, los formatos de cadena de conexión se definen en la sección Credenciales de Configuración de la indexación de blobs en Azure AI Search. Azure Storage, Azure SQL Database y Azure Cosmos DB también admiten una identidad administrada cadena de conexión que no incluya una clave de cuenta en el cadena de conexión. Para usar la identidad administrada cadena de conexión formato, siga las instrucciones para configurar una conexión de indexador a un origen de datos mediante una identidad administrada. Si va a actualizar el origen de datos, no es necesario el cadena de conexión. Los valores `<unchanged>` o `<redacted>` se pueden usar en lugar del cadena de conexión real.
contenedor	Necesario. Especifica los datos que se van a indexar mediante las `name` propiedades (obligatorias) y `query` (opcionales): :`name` para Azure SQL, especifica la tabla o vista. Puede usar nombres calificados con el esquema, como `[dbo].[mytable]`. Para Azure Cosmos DB, especifica la colección de SQL API. Para Azure Blob Storage, especifica el contenedor de almacenamiento. Para Azure Table Storage, especifica el nombre de la tabla. `query`: para Azure Cosmos DB, permite especificar una consulta que aplane un diseño de documento JSON arbitrario en un esquema plano que Azure AI Search pueda indexar. Para Azure Blob Storage, permite especificar una carpeta virtual dentro del contenedor de blobs. Por ejemplo, para la ruta de acceso de blob `mycontainer/documents/blob.pdf`, se puede usar `documents` como la carpeta virtual. Para Azure Table Storage, permite especificar una consulta que filtra el conjunto de filas que se van a importar. Para Azure SQL, no se admite la consulta. En su lugar, use vistas.
dataChangeDetectionPolicy	Opcional. Se usa para identificar los elementos de datos modificados. Las directivas compatibles varían según el tipo de origen de datos. Las directivas válidas son Directiva de detección de cambios de marca de agua alta y Directiva de detección de cambios integrada de SQL. La directiva de detección de cambios de marca de agua alta depende de una columna o propiedad existente que se actualice junto con otras actualizaciones (todas las inserciones dan lugar a una actualización de la columna de marca de agua) y el cambio en el valor es mayor. En el caso de los orígenes de datos de Cosmos DB, debe usar la `_ts` propiedad . Para Azure SQL, una columna indizada `rowversion` es el candidato ideal para su uso con la directiva de marca de agua alta. Para Azure Storage, la detección de cambios está integrada con los valores lastModified, lo que elimina cualquier necesidad de establecer dataChangeDetectionPolicy para blob o table storage. La directiva de detección de cambios integrada de SQL se usa para hacer referencia a las características de detección de cambios nativas en SQL Server. Esta directiva solo se puede usar con tablas; no se puede usar con vistas. Deberá habilitar el seguimiento de cambios para la tabla que está usando para poder emplear esta directiva. Consulte Habilitar y deshabilitar el seguimiento de cambios para obtener instrucciones. Para obtener más información sobre la compatibilidad con la detección de cambios en el indexador, consulte Conexión a contenido de Azure SQL de índice e indexación.
dataDeletionDetectionPolicy	Opcional. Se usa para identificar los elementos de datos eliminados. Actualmente, la única directiva admitida es la directiva de eliminación temporal, que identifica los elementos eliminados en función del valor de una columna o propiedad de eliminación temporal en el origen de datos. Solo se admiten columnas con valores de cadena, entero o booleano. El valor usado como `softDeleteMarkerValue` debe ser una cadena, aunque la columna correspondiente contenga números enteros o booleanos. Por ejemplo, si el valor que aparece en el origen de datos es 1, use "1" como `softDeleteMarkerValue`.
claveDeCifrado	Opcional. Se usa para cifrar el origen de datos en reposo con sus propias claves, administradas en azure Key Vault. Disponible para los servicios de búsqueda facturables creados en o después de 2019-01-01. Una `encryptionKey` sección contiene un elemento definido por `keyVaultKeyName` el usuario (obligatorio), un generado `keyVaultKeyVersion` por el sistema (obligatorio) y un elemento que `keyVaultUri` proporciona la clave (obligatorio, también denominado nombre DNS). Un URI de ejemplo podría ser "https://my-keyvault-name.vault.azure.net". Opcionalmente, puede especificar `accessCredentials` si no usa una identidad de sistema administrada. Las propiedades de `accessCredentials` incluyen `applicationId` (Microsoft Entra ID identificador de aplicación al que se concedieron permisos de acceso a la Key Vault de Azure especificada) y `applicationSecret` (clave de autenticación de la aplicación registrada). Un ejemplo de la sección siguiente ilustra la sintaxis.

Response

Para obtener una solicitud correcta: "201 Creado".

Ejemplos

Ejemplo: Azure SQL con detección de cambios (directiva de detección de cambios de marca de agua alta)

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

Ejemplo: Azure SQL con detección de cambios (directiva de Change Tracking integrada de 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" }
}

Ejemplo: Azure SQL con detección de cambios con detección de eliminación

Recuerde que las propiedades para la detección de eliminación son softDeleteColumnName y 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" }  
}

Ejemplo: Origen de datos solo con propiedades necesarias

Las propiedades opcionales relacionadas con la detección de cambios y eliminación se pueden omitir si solo piensa usar el origen de datos para una copia única de los datos:

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

Ejemplo: omisión de credenciales

Si tiene previsto actualizar el origen de datos, las credenciales no son necesarias. Los valores <unchanged> o <redacted> se pueden usar en lugar del cadena de conexión.

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

Ejemplo: Claves de cifrado

Las claves de cifrado son claves administradas por el cliente que se usan para el cifrado adicional. Para más información, consulte Cifrado mediante claves administradas por el cliente en 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)"}
      }
}