Partager via

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

  • Article

s’applique à: 2023-07-01-Preview. Cette version n’est plus prise en charge. mettre à niveau immédiatement vers une version plus récente.

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’indexeur à d’autres ressources Azure :

  • « informations d’identification » 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 l’accès en lecture aux données.
  • « identité » accepte une identité managée affectée par l’utilisateur. Cette propriété est de premier niveau pour les connexions de données. Il est également sous « encryptionKey » pour récupérer une clé gérée par le client dans Azure Key Vault.
  • prise en charge des Azure Files 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 « NativeBlobSoftDeleteDeletionDetectionPolicy » pour les indexeurs d’objets blob.
  • prise en charge des Azure Database pour MySQL est en préversion. Utilisez une API en préversion pour indexer à partir de cette source de données.
  • l’API MongoDB Cosmos DB et l’API Gremlin prise en charge sont en préversion. Utilisez une API en préversion pour indexer à partir de cette source de données.

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

Vous pouvez utiliser POST ou PUT sur une demande de création. Pour l’une ou l’autre, le corps de la requête fournit la définition d’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]

HTTPS est requis pour toutes les demandes 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.

Note

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 d’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 la 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, n’avoir aucune barre oblique ni point, et être inférieur à 128 caractères. Une fois que vous avez 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. Consultez versions de l’API pour plus de versions.

En-têtes de requête

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

Champs Description
Type de contenu Obligatoire. Définissez cette valeur sur application/json
api-key Facultatif si vous utilisez rôles Azure et qu’un jeton du 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 requête auprès de votre service de recherche. Les demandes de création doivent inclure un en-tête api-key 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 requête contient une définition de source de données, qui inclut le type de la source de données, les informations d’identification pour lire les données, ainsi qu’une détection facultative des modifications de données et des stratégies de détection de suppression de données utilisées pour identifier efficacement les données modifiées ou supprimées dans la source de données lorsqu’elles sont utilisées avec un indexeur planifié périodiquement

Le code JSON suivant est une représentation générale des parties principales 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 contient les propriétés suivantes :

Propriété Description
nom Obligatoire. Nom de la source de données. Un nom de source de données ne doit contenir que des lettres 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
azureblob Azure Data Lake Storage Gen2 pour Stockage Blob Azure
azurefiles pour Stockage Fichier Azure
azuresql pour Azure SQL Database
azuretable pour Stockage Table Azure
cosmosdb pour l’API SQL Azure Cosmos DB, api MongoDB,
mysql d’API Gremlin pour Azure Database pour MySQL
informations d’identification Obligatoire. Contient une propriété connectionString 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 Optionnel. Spécifie le mécanisme fourni par la plateforme de données pour identifier les éléments de données modifiés.
dataDeletionDetectionPolicy Optionnel. Identifie la façon dont la plateforme de données supprime les données.
encryptionKey Optionnel. Utilisé pour un chiffrement supplémentaire des informations d’identification de source de données, via 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 2019-01-01.
handicapé Optionnel. 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é Optionnel. Il contient une 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 de credentials avoir la 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é identity a la 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 spécifiée précédemment est effacée.

Réponse

Pour une demande réussie : 201 Créé si une nouvelle source de données a été créée et 204 Aucun 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 de 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 qui a 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 détection des modifications (stratégie de détection des modifications de 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 suivi des modifications 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ée ou modifiée

Si vous envisagez 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 Encryption à 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 de 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 dotée d’une identité managée affectée par l’utilisateur affecté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ôles 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
conteneur Spécifie le conteneur, la collection, la table ou la vue contenant les données à indexer.
informations d’identification Contient une propriété connectionString qui spécifie comment 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
nom 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 de schéma, tels que [dbo].[mytable]. Pour Stockage Table Azure, spécifie le nom de la table.
requête Optionnel. Pour Azure Cosmos DB, vous permet de spécifier une requête qui aplatit une disposition de document JSON arbitraire dans un schéma plat qu’Azure AI Search peut indexer. Pour Stockage Blob Azure, vous pouvez spécifier un dossier virtuel dans le conteneur d’objets blob. Par exemple, pour le chemin d’accès d’objet blob mycontainer/documents/blob.pdf, documents pouvez ê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).

Pouvoirs

Contient une propriété « connectionString » qui spécifie comment 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 source de données, la chaîne de connexion n’est pas requise. 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 la chaîne de connexion. Le format de la chaîne de connexion dépend du type de source de données :

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

Pour Azure Cosmos DB, la 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 requises. Vous pouvez les trouver dans le portail Azure .

Si vous utilisez une identité managée pour 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 ces liens pour le format de chaîne de connexion : Stockage Azure , cosmos DB,SQL Database).

Les attributions de rôles délimitées à la source de données externe déterminent si l’indexeur peut se connecter, et 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 l'« identité » n’est pas spécifiée ou null, la connexion est via l’identité managé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 en fonction du type de source de données.

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

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

SqlIntegratedChangeDetectionPolicy est 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 ; elle ne peut pas être utilisée avec des vues. Vous devez activer le suivi des modifications pour la table que vous utilisez avant de pouvoir utiliser cette stratégie. Consultez Activer et désactiver le suivi des modifications pour obtenir des instructions.
highWaterMarkColumnName Obligatoire pour HighWatermarkChangeDetectionPolicy. Pour Cosmos DB, la colonne doit être _ts propriété. Pour Azure SQL, une colonne rowversion indexée est recommandée. Pour stockage Azure, la détection des modifications est intégrée à l’aide de valeurs lastModified, ce qui élimine toute nécessité 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 en fonction du type de source de données.

Attribut Description
dataDeletionDetectionPolicy Optionnel. 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 l’état de suppression d’une ligne. Par exemple, vous pouvez créer une colonne nommée « IsDeleted ». Seules les colonnes avec des valeurs de type chaîne, entier ou booléen sont prises en charge.
softDeleteMarkerValue Obligatoire. Valeur de la colonne de suppression réversible. La valeur utilisée comme softDeleteMarkerValue doit être une chaîne, même si la colonne correspondante contient des entiers ou des booléens. 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 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 des clés de chiffrement gérées par le client (CMK) supplémentaires. 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 est disponible uniquement pour les services de recherche créés sur ou après 2019-01-01.

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 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 « identité » et « accessCredentials », et la demande s’authentifie à l’aide de l’identité managée. Si le service de recherche a une identité affectée par l’utilisateur et une attribution de rôle, 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 peut être https://my-keyvault-name.vault.azure.net.
accessCredentials Omettez si vous utilisez une identité managée. Dans le cas contraire, les propriétés de accessCredentials incluent applicationId (ID d’application Azure Active Directory disposant des autorisations d’accès à votre coffre de clés Azure spécifié) et applicationSecret (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 de 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