Creación o actualización del origen de datos (API REST de versión preliminar)

  • Artículo

Se aplica a: 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Importante

2023-07-01-Preview (sin cambios).

2021-04-30-Preview agrega compatibilidad con identidad administrada para conexiones de indexador a otros recursos de Azure:

  • "credentials" acepta un identificador de recurso de Azure como valor, siempre que el servicio de búsqueda se ejecute en una identidad administrada y las asignaciones de roles de Azure concedan acceso de lectura a los datos.
  • "identity" acepta una identidad administrada asignada por el usuario. Esta propiedad es de primer nivel para las conexiones de datos. También se encuentra en "encryptionKey" para recuperar una clave administrada por el cliente en Azure Key Vault.
  • Azure Files compatibilidad está en versión preliminar. Use una API en versión preliminar para indexar desde este origen de datos.

2020-06-30-Preview agrega:

  • "dataDeletionDetectionPolicy" acepta "NativeBlobSoftDeleteDeletionDetectionPolicy" para los indexadores de blobs.
  • Azure Database for MySQL compatibilidad está en versión preliminar. Use una API en versión preliminar para indexar desde este origen de datos.
  • La api de MongoDB de Cosmos DB y la compatibilidad con Gremlin API se encuentra en versión preliminar. Use una API en versión preliminar para indexar desde este origen de datos.

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 admitidos.

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

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

Para las solicitudes de actualización, use PUT y especifique el nombre del indexador 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 sobrescribe mediante la nueva definición.

Nota

Una vez que existe un origen de datos, no se puede cambiar la propiedad type en una solicitud de actualización. En su lugar, debe crear un nuevo origen de datos con el tipo que desee.

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 preliminar actual es 2023-07-01-Preview. 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 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 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" : (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)"}
      }
}

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 iniciar 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:
adlsgen2
para Azure Data Lake Storage Gen2
azureblob para Azure Blob Storage
azurefiles para Azure File Storage
azuresql para Azure SQL Database
azuretable for Azure Table Storage
cosmosdb para Azure Cosmos DB API de SQL, API de MongoDB, API
mysql de Gremlin para Azure Database for MySQL
credentials Necesario. Contiene una connectionString propiedad que especifica cómo conectarse.
contenedor Necesario. Especifica el contenedor, la colección, la tabla o la vista que contiene los datos que se van a indexar.
dataChangeDetectionPolicy Opcional. Especifica el mecanismo proporcionado por la plataforma de datos para identificar los elementos de datos modificados.
dataDeletionDetectionPolicy Opcional. Identifica cómo la plataforma de datos elimina los datos.
encryptionKey Opcional. Se usa para el cifrado adicional de credenciales de origen de datos, mediante claves de cifrado administradas por el cliente (CMK) en Azure Key Vault. Disponible para los servicios de búsqueda facturables creados en o después del 2019-01-01.
deshabilitado Opcional. Valor booleano que indica si el indexador se crea en un estado deshabilitado, lo que impide que se ejecute inmediatamente. El valor predeterminado es false.
identidad Opcional. Contiene un userAssignedIdentity de tipo #Microsoft.Azure.Search.DataUserAssignedIdentity y especifica la identidad administrada asignada por el usuario del recurso externo. Esta propiedad depende de credentials tener el cadena de conexión en el formato correcto (un identificador de recurso) para las conexiones de identidad administradas para cada tipo de origen de datos.

Si la identity propiedad es null, la conexión a un identificador de recurso se realiza mediante la propiedad administrada por el sistema.

Si esta propiedad se asigna al tipo #Microsoft.Azure.Search.DataNoneIdentity, se borra cualquier identidad explícita especificada anteriormente.

Response

Para efectuar una solicitud correcta: 201 Creado si se ha creado un origen de datos nuevo, y 204 Sin contenido si se ha actualizado un origen de datos existente.

Ejemplos

Ejemplo: roles de Azure y una identidad administrada asignada por el sistema

Si el servicio de búsqueda tiene una identidad administrada asignada por el sistema y una asignación de roles, la conexión del origen de datos puede ser el identificador de recurso único de la cuenta de almacenamiento.

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

Ejemplo: roles de Azure y una identidad administrada asignada por el usuario (versión preliminar)

En este ejemplo se muestra una conexión autenticada de Azure AD para un servicio de búsqueda que tiene una identidad administrada asignada por el usuario.

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

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 la 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: Uso de la opción de credencial sin cambios o redactadas

Si piensa 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 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)"}
      }
}

Ejemplo: Conexiones de almacén de claves de cifrado por los servicios de búsqueda que tienen una identidad administrada asignada por el usuario

En este ejemplo se omite accessCredentials. Para un recurso que tenga asignada una identidad administrada asignada por el usuario, puede especificar la identidad en encryptionKey y recuperar la clave mediante esa identidad y asignaciones de roles de 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"
        }
    }
}

Definiciones

Vínculo Descripción
container Especifica el contenedor, la colección, la tabla o la vista que contiene los datos que se van a indexar.
credentials Contiene una connectionString propiedad que especifica cómo se conecta un indexador a un recurso de Azure.
dataChangeDetectionPolicy Especifica el mecanismo proporcionado por la plataforma de datos para identificar los datos modificados.
dataDeletionDetectionPolicy Especifica el mecanismo para detectar datos eliminados.
encryptionKey Configura una conexión a Azure Key Vault para el cifrado administrado por el cliente.

contenedor

Especifica el contenedor, la colección, la tabla o la vista que contiene los datos que se van a indexar.

Atributo Descripción
name Necesario. Para Azure Cosmos DB, especifica la colección de SQL API. Para Azure Blob Storage, especifica el contenedor de almacenamiento. Para Azure SQL, especifica la tabla o vista. Puede usar nombres calificados con el esquema, como [dbo].[mytable]. Para Azure Table Storage, especifica el nombre de la tabla.
Query Opcional. Para Azure Cosmos DB, permite especificar una consulta que aplane un diseño arbitrario de documentos JSON 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 (use vistas en su lugar).

credentials

Contiene una propiedad "connectionString" que especifica cómo se conecta un indexador a un recurso de Azure.

Atributo Descripción
connectionString Necesario. Especifica una conexión a un origen de datos de indexador. Si va a actualizar la definición del 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.

En el caso de las conexiones que se autentican mediante claves o credenciales de inicio de sesión, esos valores son visibles en el cadena de conexión. 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 formato siguiente: "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.

Si usa una identidad administrada para autenticarse, puede omitir las credenciales en la conexión.

Para las conexiones que se autentican mediante una identidad administrada, el cadena de conexión especifica el identificador de recurso de Azure (consulte estos vínculos para cadena de conexión formato: Azure Storage, Cosmos DBSQL Database).

Las asignaciones de roles cuyo ámbito es el origen de datos externo determinan si el indexador puede conectarse y el servicio de búsqueda debe configurarse para ejecutarse como un servicio de confianza en Azure Active Directory.

Si también se especifica la propiedad "identity", la conexión se realiza mediante la identidad administrada asignada por el usuario del servicio de búsqueda proporcionada por la propiedad "identity". De lo contrario, si "identity" no se especifica o null, la conexión se realiza a través de la identidad administrada por el sistema.

dataChangeDetectionPolicy

Especifica el mecanismo proporcionado por la plataforma de datos para identificar los datos modificados. Las directivas compatibles varían según el tipo de origen de datos.

Atributo Descripción
dataChangeDetectionPolicy Opcional. Las directivas válidas incluyen HighWatermarkChangeDetectionPolicy o SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy 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.

SqlIntegratedChangeDetectionPolicyse 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.
highWaterMarkColumnName Es obligatorio para HighWatermarkChangeDetectionPolicy. Para Cosmos DB, la columna debe ser _ts propiedad. Para Azure SQL, se recomienda una columna indizadarowversion. Para Azure Storage, la detección de cambios está integrada con los valores lastModified, lo que elimina cualquier necesidad de establecer dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Especifica el mecanismo proporcionado por la plataforma de datos para identificar los datos eliminados. Las directivas compatibles varían según el tipo de origen de datos.

Atributo Descripción
dataDeletionDetectionPolicy Opcional. Los valores válidos son SoftDeleteColumnDeletionDetectionPolicy o NativeBlobSoftDeleteDeletionDetectionPolicy (consulte Eliminación temporal de blobs nativos (versión preliminar)).

Actualmente, la única directiva disponible con carácter general esSoftDeleteColumnDeletionDetectionPolicy, que identifica los elementos eliminados en función del valor de una columna o propiedad de eliminación temporal en el origen de datos.

softDeleteColumnName" Necesario. Nombre de una columna del origen de datos que proporciona un valor que especifica el estado de eliminación de una fila. Por ejemplo, podría crear una columna denominada "IsDeleted". Solo se admiten las columnas con valores de cadena, enteros o booleanos.
softDeleteMarkerValue Necesario. Valor de la columna de eliminación temporal. 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. Si el indexador lee este valor de la columna de eliminación temporal, elimina el documento de búsqueda correspondiente del índice de búsqueda.

claveDeCifrado

Configura una conexión a Azure Key Vault para claves de cifrado administradas por el cliente (CMK) complementarias. El cifrado con claves administradas por el cliente no está disponible para los servicios gratuitos. Para los servicios facturables, solo está disponible para los servicios de búsqueda creados en o después de 2019-01-01.

Se debe autenticar una conexión al almacén de claves. Puede usar "accessCredentials" o una identidad administrada para este fin.

Las identidades administradas pueden ser asignadas por el sistema o por el usuario (versión preliminar). Si el servicio de búsqueda tiene una identidad administrada asignada por el sistema y una asignación de roles que concede acceso de lectura al almacén de claves, puede omitir "identity" y "accessCredentials", y la solicitud se autenticará mediante la identidad administrada. Si el servicio de búsqueda tiene la identidad asignada por el usuario y la asignación de roles, establezca la propiedad "identity" en el identificador de recurso de esa identidad.

Atributo Descripción
keyVaultKeyName Necesario. Nombre de la clave de Azure Key Vault que se usa para el cifrado.
keyVaultKeyVersion Necesario. Versión de la clave de Azure Key Vault.
keyVaultUri Necesario. URI de Azure Key Vault (también denominado nombre DNS) que proporciona la clave. Un identificador URI de ejemplo podría ser https://my-keyvault-name.vault.azure.net.
accessCredentials Omita si usa una identidad administrada. De lo contrario, las propiedades de accessCredentials incluyen applicationId (un identificador de aplicación de Azure Active Directory que tiene permisos de acceso a la Key Vault de Azure especificada) y applicationSecret (la clave de autenticación de la aplicación de Azure AD especificada).
identidad Opcional a menos que use una identidad administrada asignada por el usuario para la conexión del servicio de búsqueda a Azure Key Vault. El formato es "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Consulte también