Compartir a través de

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

  • Artículo

se aplica a: 2023-07-01-Preview. Esta versión ya no se admite. Actualizar inmediatamente a una versión más reciente.

Importante

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

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

  • "credenciales" 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.
  • "identidad" 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.
  • compatibilidad con azure Files 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.
  • la compatibilidad con azure Database for MySQL 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 está 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, proporcionando la información de conexión para la actualización de datos a petición o programada de un índice de destino, extraer datos de orígenes de datos admitidos.

Puede usar POST o PUT en una solicitud de creación. Para cualquiera de ellas, 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 URI

Parámetro Descripción
nombre del servicio Obligatorio. 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 se usa PUT. El nombre debe ser 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 Obligatorio. Consulte versiones de API para obtener más versiones.

Encabezados de solicitud

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

Campos Descripción
Tipo de contenido Obligatorio. 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 encabezado api-key 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 del origen de datos, las credenciales para leer los datos, así como una directiva opcional de detección de cambios de datos y detección de eliminación de datos que se usan para identificar de forma eficaz los datos modificados 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" : (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
nombre Obligatorio. 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.
descripción Una descripción opcional.
tipo Obligatorio. Debe ser uno de los tipos de origen de datos admitidos: para de Azure Data Lake Storage Gen2 para azure Blob Storage para azure File Storage para azure SQL Database para Azure Table Storage para lade LA API de SQL de Azure Cosmos DB , api de MongoDB, de Gremlin API para Azure Database for MySQL
credenciales Obligatorio. Contiene una propiedad connectionString que especifica cómo conectarse.
contenedor Obligatorio. 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 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, a través de 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. False de forma predeterminada.
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 la cadena de conexión en el formato correcto (un identificador de recurso) para las conexiones de identidad administrada para cada tipo de origen de datos.

Si la propiedad identity 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.

Respuesta

Para una solicitud correcta: 201 Creado si se creó un nuevo origen de datos y 204 Sin contenido si se actualizó 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 detección de cambios (directiva de seguimiento de cambios integrado 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 de : origen de datos con propiedades necesarias solo

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 la 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 censuradas

Si piensa actualizar el origen de datos, las credenciales no son necesarias. 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 de : 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 servicios de búsqueda que tienen una identidad administrada asignada por el usuario

En este ejemplo se omite accessCredentials. Para un recurso que tenga una identidad administrada asignada por el usuario asignada, 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

Enlace Descripción
de contenedor Especifica el contenedor, la colección, la tabla o la vista que contiene los datos que se van a indexar.
credenciales Contiene una propiedad connectionString 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
nombre Obligatorio. Para Azure Cosmos DB, especifica la colección de API de SQL. Para Azure Blob Storage, especifica el contenedor de almacenamiento. Para Azure SQL, especifica la tabla o vista. Puede usar nombres calificados de esquema, como [dbo].[mytable]. Para Azure Table Storage, especifica el nombre de la tabla.
consulta 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, documents se puede usar como carpeta virtual. Para Azure Table Storage, permite especificar una consulta que filtre el conjunto de filas que se va a importar. Para Azure SQL, no se admite la consulta (use vistas en su lugar).

credenciales

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

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

En el caso de las conexiones que se autentican mediante claves o credenciales de inicio de sesión, esos valores son visibles en la cadena de conexión. El formato de la cadena de conexión depende del tipo de origen de datos:

Para Azure SQL Database, esta es la cadena de conexión habitual de SQL Server. Si usa Azure Portal para recuperar la cadena de conexión, elija la opción ADO.NET connection string.

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]". Se requieren todos los valores. Puede encontrarlos en Azure Portal.

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

Para las conexiones que se autentican mediante una identidad administrada, la cadena de conexión especifica el identificador de recurso de Azure (consulte estos vínculos para el formato de cadena de conexión: Azure Storage, Cosmos DB,SQL 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 está especificado o es 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 admitidas varían en función del 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 lugar a una actualización de la columna de marca de agua) y el cambio en el valor es mayor.

SqlIntegratedChangeDetectionPolicy se usa para hacer referencia a las características nativas de detección de cambios en SQL Server. Esta directiva solo se puede usar con tablas; no se puede usar con vistas. Debe habilitar el seguimiento de cambios para la tabla que usa antes de poder usar esta directiva. Consulte Habilitación y deshabilitación del seguimiento de cambios para obtener instrucciones.
highWaterMarkColumnName Necesario para HighWatermarkChangeDetectionPolicy. Para Cosmos DB, la columna debe ser _ts propiedad. Para Azure SQL, se recomienda una columna rowversion indizada. Para Azure Storage, la detección de cambios se integra mediante 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 admitidas varían en función del 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" Obligatorio. 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 columnas con valores de cadena, entero o booleano.
softDeleteMarkerValue Obligatorio. Valor de la columna de eliminación temporal. El valor usado como softDeleteMarkerValue debe ser una cadena, incluso si la columna correspondiente contiene 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.

encryptionKey

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 del 2019-01-01.

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

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 Obligatorio. Nombre de la clave de Azure Key Vault que se usa para el cifrado.
keyVaultKeyVersion Obligatorio. Versión de la clave de Azure Key Vault.
keyVaultUri Obligatorio. URI de Azure Key Vault (también denominado nombre DNS) que proporciona la clave. Un 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 azure Key Vault especificado) 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