Créer une source de données (API REST Recherche IA Azure)

Article
03/05/2024

Dans Azure AI Search, 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 Azure prises en charge.

Vous pouvez utiliser POST ou PUT sur la demande. Pour l’une ou l’autre, le document JSON dans le corps de la demande 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]

Vous pouvez également utiliser PUT et spécifier le nom 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 mis à jour vers la nouvelle définition.

Notes

Le nombre maximal d'index que vous pouvez créer varie en fonction du niveau de tarification. Pour plus d’informations, consultez Limites du Service.

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 chiffre, ne comporter ni barres obliques ni points et comporter moins de 128 caractères. Le nom doit commencer par une lettre ou un chiffre, mais le reste du nom peut inclure n’importe quelle lettre, chiffre et tirets, tant que les tirets ne sont pas consécutifs.
api-version	Obligatoire. Consultez Versions d’API pour obtenir la liste des versions prises en charge.

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. 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 requête 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 générale 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": {
        "name": "Name of the table, view, collection, or blob container you wish to index",
        "query": (optional) 
    },
    "dataChangeDetectionPolicy" : (optional) {See below for details },
    "dataDeletionDetectionPolicy" : (optional) {See below for details },
    "encryptionKey":(optional) { }
}

La 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 doit uniquement contenir 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 : `azuresql` pour Azure SQL Database, Azure SQL Managed Instance ou SQL Server instance s’exécutant sur une machine virtuelle `cosmosdb` Azure pour Azure Cosmos DB for NoSQL, Azure Cosmos DB for MongoDB (préversion) ou Azure Cosmos DB pour Apache Gremlin (préversion) `azureblob` pour Stockage Blob Azure `adlsgen2` pour Azure Data Lake Storage Gen2 `azuretable` pour stockage `azurefile` Table Azure pour Azure Files (préversion) `mysql` pour Azure Database pour MySQL (préversion) `sharepoint` pour SharePoint dans Microsoft 365 (préversion)
credentials	Obligatoire. Il contient une `connectionString` propriété qui spécifie le chaîne de connexion pour la source de données. Le format de la 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. Par Stockage Blob Azure, les formats de chaîne de connexion sont définis dans la section Informations d’identification de La procédure de configuration de l’indexation d’objets blob dans Azure AI Search. Stockage Azure, Azure SQL Database et Azure Cosmos DB prennent également en charge une identité managée chaîne de connexion qui n’inclut pas de clé de compte dans le chaîne de connexion. Pour utiliser le format de chaîne de connexion d’identité managée, suivez les instructions de Configuration d’une connexion d’indexeur à une source de données à l’aide d’une identité managée. Si vous mettez à jour la source de données, l’chaîne de connexion n’est pas nécessaire. Les valeurs `<unchanged>` ou `<redacted>` peuvent être utilisées à la place de la chaîne de connexion réelle.
conteneur	Obligatoire. Spécifie les données à indexer à l’aide des `name` propriétés (obligatoires) et `query` (facultatives) :`name` : 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 Azure Cosmos DB, spécifie la collection d’API SQL. Pour Stockage Blob Azure, spécifie le conteneur de stockage. Pour Stockage Table Azure, spécifie le nom de la table. `query`: 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 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. Par Azure SQL, la requête n’est pas prise en charge. Utilisez des vues à la place.
dataChangeDetectionPolicy	facultatif. Utilisé pour identifier les éléments de données modifiés. Les stratégies prises en charge varient selon le type de source de données. Les stratégies valides sont la stratégie de détection des modifications en filigrane élevé et la stratégie de détection des modifications intégrée SQL. La stratégie de détection des modifications en filigrane élevé dépend d’une colonne ou d’une propriété existante qui est mise à jour conjointement avec d’autres mises à jour (toutes les insertions entraînent une mise à jour de la colonne en filigrane), et la modification de la valeur est plus élevée. Pour les sources de données Cosmos DB, vous devez utiliser la `_ts` propriété . Pour Azure SQL, une colonne indexée `rowversion` est le candidat idéal pour une utilisation avec la stratégie de limite supérieure. Pour le 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 pour le stockage d’objets blob ou de table. La stratégie de détection des modifications intégrée SQL est utilisée 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 . Pour plus d’informations sur la prise en charge de la détection des modifications dans l’indexeur, consultez Se connecter au contenu Azure SQL et l’indexer.
dataDeletionDetectionPolicy	facultatif. Utilisé pour identifier les éléments de données supprimés. Actuellement, la seule stratégie prise en charge est la stratégie de suppression réversible, qui identifie les éléments supprimés en fonction de la valeur d’une colonne ou d’une propriété de « suppression réversible » dans la source de données. Seules les colonnes avec des valeurs de chaîne, d’entier ou de type booléen sont prises en charge. 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`.
encryptionKey	facultatif. Utilisé pour chiffrer la source de données au repos avec vos propres clés, gérées dans votre Key Vault Azure. Disponible pour les services de recherche facturables créés le 01/01/2019. Une `encryptionKey` section contient un défini par `keyVaultKeyName` l’utilisateur (obligatoire), un généré par `keyVaultKeyVersion` le système (obligatoire) et un `keyVaultUri` qui fournit la clé (obligatoire, également appelé nom DNS). Un exemple d’URI peut être « https://my-keyvault-name.vault.azure.net". Si vous le souhaitez, vous pouvez spécifier `accessCredentials` si vous n’utilisez pas d’identité système managée. Propriétés de `accessCredentials` include `applicationId` (Microsoft Entra ID’ID d’application qui a obtenu des autorisations d’accès à votre Key Vault Azure spécifié) et `applicationSecret` (clé d’authentification de l’application inscrite). Un exemple de la section suivante illustre la syntaxe.

response

Pour une requête réussie : « 201 Créé ».

Exemples

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 la 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 la détection des modifications avec la détection de suppression

Rappelez-vous que les propriétés pour la 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 des modifications et des suppressions peuvent être omises si vous envisagez uniquement d’utiliser la source de données pour une copie unique 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 : omission des informations d’identification

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 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 system identity) {
        "applicationId": "Microsoft Entra ID application ID that was granted access permissions to your specified Azure Key Vault",
        "applicationSecret": "Authentication key of the registered application)"}
      }
}

Partager via