Creación de un origen de datos (API REST de Azure Cognitive Search)

En Azure Cognitive 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 admitidos.

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, empezar con una letra o un número, no tener barras diagonales ni puntos y tener menos de 128 caracteres. Después de iniciar el nombre con una letra o un número, el resto del nombre puede incluir cualquier letra, número y guiones, siempre y cuando los guiones no sean consecutivos.
api-version	Necesario. La versión estable actual es api-version=2020-06-30. Consulte Versiones de API para obtener más versiones.

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. Una clave de API es una cadena única generada por el sistema que autentica la solicitud en el servicio de búsqueda. Las solicitudes de creación deben incluir un api-key encabezado establecido en la clave de administrador (en lugar de una clave de consulta). Consulte Conexión a Cognitive Search mediante la autenticación de claves para obtener 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 directivas de detección de cambios y eliminación de datos que se usan para identificar de forma eficaz los datos cambiados o eliminados en el origen de datos cuando se utiliza con un indizador 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, números o guiones, no puede comenzar 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 o SQL Server instancia que se ejecuta en la máquina virtual cosmosdb de Azure para la API azureblob de SQL de Azure Cosmos DB para Azure Blob Storage adlsgen2 para azuretable Azure Data Lake Storage Gen2 para Azure Table Storage
credentials	Necesario. Contiene una connectionString propiedad que especifica la cadena de conexión para el origen de datos. El formato de la 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 la cadena de conexión, elija la ADO.NET connection string opción . Para Azure Cosmos DB, la 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 Cómo configurar la indexación de blobs en Cognitive Search. Azure Storage, Azure SQL Database y Azure Cosmos DB también admiten una cadena de conexión de identidad administrada que no incluye una clave de cuenta en la cadena de conexión. Para usar el formato de cadena de conexión de identidad administrada, 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, la cadena de conexión no es necesaria. Los valores <unchanged> o <redacted> se pueden usar en lugar de la 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 Cognitive 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 como resultado una actualización a la columna de marca de agua) y el cambio en el valor es mayor. Para los orígenes de datos de Cosmos DB, debe usar la _ts propiedad . Para Azure SQL, una columna indizada rowversion es la candidata 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 e índice Azure SQL contenido.
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 del sistema administrada. Entre las propiedades de se incluyen applicationId (identificador de aplicación de accessCredentials Azure Active Directory al que se concedieron permisos de acceso a la Key Vault de Azure especificada) y applicationSecret (clave de autenticación de la aplicación de Azure AD especificada). 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, no se requieren las credenciales. Los valores <unchanged> o <redacted> se pueden usar en lugar de la 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": "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)"}
      }
}

Consulte también

• Introducción a los indexadores
• Creación de indexadores
• API REST de Azure Cognitive Search
• Operaciones de indexador
• Reglas de nomenclatura