Partager via

Créer ou mettre à jour une source de données (API REST en préversion)

  • Article

S’applique à : 2023-07-01-Preview, 2021-04-30-Preview, 2020-06-30-Preview

Important

2023-07-01-Preview (aucune modification).

2021-04-30-Preview ajoute la prise en charge des identités managées pour les connexions d’indexeurs à d’autres ressources Azure :

  • « credentials » accepte un ID de ressource Azure comme valeur, à condition que le service de recherche s’exécute sous une identité managée et que les attributions de rôles Azure accordent un accès en lecture aux données.
  • « identity » accepte une identité managée affectée par l’utilisateur. Cette propriété est de premier niveau pour les connexions de données. Il se trouve également sous « encryptionKey » pour récupérer une clé gérée par le client dans Azure Key Vault.
  • Azure Files prise en charge est en préversion. Utilisez une API en préversion pour indexer à partir de cette source de données.

2020-06-30-Preview ajoute :

  • « dataDeletionDetectionPolicy » accepte « NativeBlobSoftDeleteDeleteDeletionDetectionPolicy » pour les indexeurs d’objets blob.
  • Azure Database pour MySQL prise en charge est en préversion. Utilisez une API en préversion pour indexer à partir de cette source de données.
  • La prise en charge de l’API MongoDB Cosmos DB et de l’API Gremlin est en préversion. Utilisez une API en préversion pour indexer à partir de cette source de données.

Dans Recherche Azure AI, une source de données est utilisée avec les indexeurs, fournissant les informations de connexion pour l’actualisation des données à la demande ou planifiée d’un index cible, en extrayant les données des sources de données prises en charge.

Vous pouvez utiliser POST ou PUT sur une demande de création. Pour l’un ou l’autre, le corps de la requête fournit la définition de l’objet.

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

Pour les demandes de mise à jour, utilisez PUT et spécifiez le nom de l’indexeur sur l’URI.

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

Le protocole HTTPS est requis pour toutes les requêtes de service. Si l’objet n’existe pas, il est créé. S’il existe déjà, il est remplacé à l’aide de la nouvelle définition.

Notes

Une fois qu’une source de données existe, vous ne pouvez pas modifier la propriété de type sur une demande de mise à jour. Au lieu de cela, vous devez créer une source de données à l’aide du type souhaité.

Paramètres URI

Paramètre Description
nom du service Obligatoire. Définissez cette valeur sur le nom unique défini par l’utilisateur de votre service de recherche.
nom de source de données Obligatoire sur l’URI si vous utilisez PUT. Le nom doit être en minuscules, commencer par une lettre ou un nombre, avoir aucune barre oblique ou point, et comporter moins de 128 caractères. Après avoir démarré le nom avec une lettre ou un nombre, le reste du nom peut inclure n’importe quelle lettre, nombre et tirets, tant que les tirets ne sont pas consécutifs.
api-version Obligatoire. La version d’évaluation actuelle est 2023-07-01-Preview. Pour plus d’informations, consultez Versions de l’API .

En-têtes de requête

Le tableau suivant décrit les en-têtes de demande obligatoires et facultatifs.

Champs Description
Content-Type Obligatoire. À définir avec la valeur application/json
api-key Facultatif si vous utilisez des rôles Azure et qu’un jeton de porteur est fourni sur la demande, sinon une clé est requise. Une clé API est une chaîne unique générée par le système qui authentifie la demande auprès de votre service de recherche. Les demandes de création doivent inclure un api-key en-tête défini sur votre clé d’administration (par opposition à une clé de requête). Pour plus d’informations, consultez Se connecter à Azure AI Search à l’aide de l’authentification par clé .

Corps de la demande

Le corps de la demande contient une définition de source de données, qui inclut le type de la source de données, des informations d'identification pour lire les données, ainsi que des stratégies facultatives de détection des modifications et suppressions de données, qui permettent d'identifier efficacement les données modifiées ou supprimées dans la source de données quand celle-ci est utilisée avec un indexeur planifié à intervalles réguliers.

Le code JSON suivant est une représentation de haut niveau des parties main de la définition.

{   
    "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 requête peut contenir les propriétés suivantes :

Propriété Description
name Obligatoire. Nom de la source de données. Un nom de source de données ne doit contenir que des minuscules, des chiffres ou des tirets, ne peut pas commencer ou se terminer par des tirets et est limité à 128 caractères.
description Description facultative.
type Obligatoire. Doit être l’un des types de sources de données pris en charge :
adlsgen2
pour Azure Data Lake Storage Gen2
azureblob pour Stockage Blob Azure
azurefiles pour stockage
azuresql de fichiers Azure pour Azure SQL Database
azuretable pour stockage table
cosmosdb Azure pour Azure Cosmos API SQL de base de données, API MongoDB, API
mysql Gremlin pour Azure Database pour MySQL
credentials Obligatoire. Contient une connectionString propriété qui spécifie comment se connecter.
conteneur Obligatoire. Spécifie le conteneur, la collection, la table ou la vue contenant les données à indexer.
dataChangeDetectionPolicy facultatif. Spécifie le mécanisme fourni par la plateforme de données pour identifier les éléments de données modifiés.
dataDeletionDetectionPolicy facultatif. Identifie la façon dont la plateforme de données supprime les données.
encryptionKey facultatif. Utilisé pour le chiffrement supplémentaire des informations d’identification de source de données, via des clés de chiffrement gérées par le client (CMK) dans Azure Key Vault. Disponible pour les services de recherche facturables créés le ou après le 01/01/01/2019.
disabled facultatif. Valeur booléenne indiquant si l’indexeur est créé dans un état désactivé, ce qui l’empêche de s’exécuter immédiatement. False par défaut.
identité facultatif. Il contient un userAssignedIdentity de type #Microsoft.Azure.Search.DataUserAssignedIdentity et spécifie l’identité managée affectée par l’utilisateur de la ressource externe. Cette propriété dépend credentials de l’chaîne de connexion au format approprié (id de ressource) pour les connexions d’identité managée pour chaque type de source de données.

Si la propriété a la identity valeur Null, la connexion à un ID de ressource est établie à l’aide de la propriété gérée par le système.

Si cette propriété est affectée au type #Microsoft.Azure.Search.DataNoneIdentity, toute identité explicite précédemment spécifiée est effacée.

response

Pour une requête réussie : 201 Créé est renvoyé si une source de données a été créée, et 204 Pas de contenu si une source de données existante a été mise à jour.

Exemples

Exemple : rôles Azure et identité managée affectée par le système

Si votre service de recherche a une identité managée affectée par le système et une attribution de rôle, la connexion à la source de données peut être l’ID de ressource unique de votre compte de stockage.

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

Exemple : rôles Azure et identité managée affectée par l’utilisateur (préversion)

Cet exemple illustre une connexion authentifiée Azure AD pour un service de recherche doté d’une identité managée affectée par l’utilisateur.

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

Exemple : Azure SQL avec la détection des modifications (stratégie de détection des changements en filigrane élevé)

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

Exemple : Azure SQL avec détection des modifications (stratégie de Change Tracking intégrée 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" }
}

Exemple : Azure SQL avec détection des modifications avec détection de suppression

Rappelez-vous que les propriétés de détection de suppression sont « softDeleteColumnName » et « 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" }  
}

Exemple : source de données avec les propriétés requises uniquement

Les propriétés facultatives liées à la détection de modification et de suppression peuvent être omises si vous envisagez uniquement d’utiliser la source de données pour une copie ponctuelle des données :

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

Exemple : utilisation de l’option d’informations d’identification inchangées ou supprimées

Si vous avez l’intention de mettre à jour la source de données, les informations d’identification ne sont pas requises. Les valeurs <unchanged> ou <redacted> peuvent être utilisées à la place de la chaîne de connexion.

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

Exemple : clés de chiffrement

Les clés de chiffrement sont des clés gérées par le client utilisées pour un chiffrement supplémentaire. Pour plus d’informations, consultez Chiffrement à l’aide de clés gérées par le client dans 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)"}
      }
}

Exemple : Chiffrement des connexions au coffre de clés par les services de recherche ayant une identité managée affectée par l’utilisateur

Cet exemple omet accessCredentials. Pour une ressource à laquelle une identité managée affectée par l’utilisateur lui est attribuée, vous pouvez spécifier l’identité dans encryptionKey et récupérer la clé à l’aide de cette identité et des attributions de rôle 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"
        }
    }
}

Définitions

Lien Description
container Spécifie le conteneur, la collection, la table ou la vue contenant les données à indexer.
credentials Contient une connectionString propriété qui spécifie la façon dont un indexeur se connecte à une ressource Azure.
dataChangeDetectionPolicy Spécifie le mécanisme fourni par la plateforme de données pour identifier les données modifiées.
dataDeletionDetectionPolicy Spécifie le mécanisme de détection des données supprimées.
encryptionKey Configure une connexion à Azure Key Vault pour le chiffrement géré par le client.

conteneur

Spécifie le conteneur, la collection, la table ou la vue contenant les données à indexer.

Attribut Description
name Obligatoire. Pour Azure Cosmos DB, spécifie la collection d’API SQL. Pour Stockage Blob Azure, spécifie le conteneur de stockage. Pour Azure SQL, spécifie la table ou la vue. Vous pouvez utiliser des noms qualifiés par schéma, tels que [dbo].[mytable]. Pour Stockage table Azure, spécifie le nom de la table.
query facultatif. Pour Azure Cosmos DB, vous permet de spécifier une requête qui aplatit une disposition de document JSON arbitraire en un schéma plat que Recherche Azure AI peut indexer. Par Stockage Blob Azure, vous permet de spécifier un dossier virtuel dans le conteneur d’objets blob. Par exemple, pour le chemin d’accès aux objets blob mycontainer/documents/blob.pdf, documents peut être utilisé comme dossier virtuel. Pour Stockage Table Azure, vous permet de spécifier une requête qui filtre l’ensemble de lignes à importer. Pour Azure SQL, la requête n’est pas prise en charge (utilisez plutôt des vues).

credentials

Contient une propriété « connectionString » qui spécifie la façon dont un indexeur se connecte à une ressource Azure.

Attribut Description
connectionString Obligatoire. Spécifie une connexion à une source de données d’indexeur. Si vous mettez à jour la définition de la source de données, le chaîne de connexion n’est pas obligatoire. Les valeurs <unchanged> ou <redacted> peuvent être utilisées à la place de la chaîne de connexion réelle.

Pour les connexions authentifiées à l’aide de clés ou d’informations d’identification de connexion, ces valeurs sont visibles dans le chaîne de connexion. Le format du chaîne de connexion dépend du type de source de données :

pour Azure SQL Base de données, il s’agit de la SQL Server chaîne de connexion habituelle. Si vous utilisez Portail Azure pour récupérer le chaîne de connexion, choisissez l’option ADO.NET connection string .

Pour Azure Cosmos DB, le chaîne de connexion doit être au format suivant : "AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]". Toutes les valeurs sont obligatoires. Elles sont disponibles sur le Portail Azure.

Si vous utilisez une identité managée pour vous authentifier, vous pouvez omettre les informations d’identification sur la connexion.

Pour les connexions authentifiées à l’aide d’une identité managée, la chaîne de connexion spécifie l’ID de ressource Azure (consultez les liens suivants pour chaîne de connexion format : Stockage Azure, Cosmos DB,SQL Database).

Les attributions de rôles limitées à la source de données externe déterminent si l’indexeur peut se connecter et si le service de recherche doit être configuré pour s’exécuter en tant que service approuvé dans Azure Active Directory.

Si la propriété « identity » est également spécifiée, la connexion est établie à l’aide de l’identité managée affectée par l’utilisateur du service de recherche fournie par la propriété « identity ». Sinon, si « identité » n’est pas spécifié ou null, la connexion se fait via l’identité gérée par le système.

dataChangeDetectionPolicy

Spécifie le mécanisme fourni par la plateforme de données pour identifier les données modifiées. Les stratégies prises en charge varient selon le type de source de données.

Attribut Description
dataChangeDetectionPolicy facultatif. Les stratégies valides incluent HighWatermarkChangeDetectionPolicy ou SqlIntegratedChangeDetectionPolicy.

HighWatermarkChangeDetectionPolicy dépend d’une colonne ou d’une propriété existante qui est mise à jour en tandem avec d’autres mises à jour (toutes les insertions entraînent une mise à jour de la colonne filigrane), et la modification de la valeur est plus élevée.

SqlIntegratedChangeDetectionPolicyest utilisé pour référencer les fonctionnalités de détection des modifications natives dans SQL Server. Cette stratégie ne peut être utilisée qu’avec des tables ; Il ne peut pas être utilisé avec des vues. Pour pouvoir appliquer cette stratégie, vous devez activer le suivi des modifications sur la table. Pour plus d’informations, consultez la section Activer et désactiver le suivi des modifications .
highWaterMarkColumnName Requis pour HighWatermarkChangeDetectionPolicy. Pour Cosmos DB, la colonne doit être _ts une propriété. Pour Azure SQL, une colonne indexée rowversion est recommandée. Pour stockage Azure, la détection des modifications est intégrée à l’aide de valeurs lastModified, ce qui élimine tout besoin de définir dataChangeDetectionPolicy.

dataDeletionDetectionPolicy

Spécifie le mécanisme fourni par la plateforme de données pour identifier les données supprimées. Les stratégies prises en charge varient selon le type de source de données.

Attribut Description
dataDeletionDetectionPolicy facultatif. Les valeurs valides sont SoftDeleteColumnDeletionDetectionPolicy ou NativeBlobSoftDeleteDeletionDetectionPolicy (voir Suppression réversible d’objets blob natifs (préversion)).

Actuellement, la seule stratégie généralement disponible estSoftDeleteColumnDeletionDetectionPolicy, qui identifie les éléments supprimés en fonction de la valeur d’une colonne ou d’une propriété « suppression réversible » dans la source de données.

softDeleteColumnName » Obligatoire. Nom d’une colonne dans votre source de données fournissant une valeur qui spécifie la suppression d’une ligne status. Par exemple, vous pouvez créer une colonne nommée « IsDeleted ». Seules les colonnes contenant des valeurs de chaîne, d'entier ou booléennes sont prises en charge.
softDeleteMarkerValue Obligatoire. Valeur de la colonne de suppression réversible. La valeur utilisée en tant que softDeleteMarkerValue doit être une chaîne de caractère, même si la colonne correspondante contient des entiers ou des valeurs booléennes. Par exemple, si la valeur qui apparaît dans votre source de données est 1, utilisez « 1 » comme softDeleteMarkerValue. Si l’indexeur lit cette valeur à partir de la colonne de suppression réversible, il supprime le document de recherche correspondant de l’index de recherche.

encryptionKey

Configure une connexion à Azure Key Vault pour les clés de chiffrement supplémentaires gérées par le client (CMK). Le chiffrement avec des clés gérées par le client n’est pas disponible pour les services gratuits. Pour les services facturables, il n’est disponible que pour les services de recherche créés à compter du 01/01/01/2019.

Une connexion au coffre de clés doit être authentifiée. Vous pouvez utiliser « accessCredentials » ou une identité managée à cet effet.

Les identités managées peuvent être affectées par le système ou par l’utilisateur (préversion). Si le service de recherche a à la fois une identité managée affectée par le système et une attribution de rôle qui accorde l’accès en lecture au coffre de clés, vous pouvez omettre à la fois « identity » et « accessCredentials », et la demande s’authentifiera à l’aide de l’identité managée. Si le service de recherche dispose d’une identité et d’une attribution de rôle attribuées par l’utilisateur, définissez la propriété « identity » sur l’ID de ressource de cette identité.

Attribut Description
keyVaultKeyName Obligatoire. Nom de la clé azure Key Vault utilisée pour le chiffrement.
keyVaultKeyVersion Obligatoire. Version de la clé Azure Key Vault.
keyVaultUri Obligatoire. URI d’Azure Key Vault (également appelé nom DNS) qui fournit la clé. Un exemple d’URI pourrait être https://my-keyvault-name.vault.azure.net.
accessCredentials Omettez si vous utilisez une identité managée. Sinon, les propriétés de accessCredentials include applicationId (un ID d’application Azure Active Directory disposant d’autorisations d’accès à votre Key Vault Azure spécifié) et applicationSecret (la clé d’authentification de l’application Azure AD spécifiée).
identité Facultatif, sauf si vous utilisez une identité managée affectée par l’utilisateur pour la connexion du service de recherche à Azure Key Vault. Le format est "/subscriptions/[subscription ID]/resourceGroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[managed identity name]".

Voir aussi