Adatforrás létrehozása (Azure AI Search REST API)

Cikk
03/05/2024

Az Azure AI Searchben az indexelők egy adatforrást használnak, amely megadja a célindex igény szerinti vagy ütemezett adatfrissítésének kapcsolati adatait, és adatokat kér le a támogatott Azure-adatforrásokból.

A kérelemhez használhatJA a POST vagy a PUT elemet. Mindkét esetben a kérelem törzsében található JSON-dokumentum biztosítja az objektumdefiníciót.

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

Másik lehetőségként használhatja a PUT parancsot, és megadhatja a nevet az URI-n.

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

MINDEN szolgáltatáskéréshez HTTPS szükséges. Ha az objektum nem létezik, létrejön. Ha már létezik, az új definícióra frissül.

Megjegyzés

A létrehozható indexek maximális száma tarifacsomagonként változik. További információ: Szolgáltatáskorlátok.

URI-paraméterek

Paraméter	Leírás
szolgáltatásnév	Kötelező. Állítsa be ezt a keresési szolgáltatás egyedi, felhasználó által definiált nevére.
adatforrás neve	Put használata esetén az URI-n kötelező megadni. A névnek kisbetűnek kell lennie, betűvel vagy számmal kell kezdődnie, nincsenek perjelei vagy pontjai, és 128 karakternél kevesebbnek kell lennie. A névnek betűvel vagy számmal kell kezdődnie, de a többi név tartalmazhat bármilyen betűt, számot és kötőjelet, feltéve, hogy a kötőjelek nem egymást követőek.
api-verzió	Kötelező. A támogatott verziók listáját lásd: API-verziók .

Kérelemfejlécek

Az alábbi táblázat a szükséges és nem kötelező kérésfejléceket ismerteti.

Mezők Description

Content-Type Kötelező. Állítsa a következőre: application/json

api-key Nem kötelező , ha Azure-szerepköröket használ, és egy tulajdonosi jogkivonatot ad meg a kéréshez, ellenkező esetben kulcsra van szükség. A létrehozási kérelmeknek tartalmazniuk kell egy api-key , a rendszergazdai kulcsra beállított fejlécet (a lekérdezési kulcs helyett). A részletekért lásd: Csatlakozás az Azure AI Search szolgáltatáshoz kulcshitelesítés használatával .

Mezők	Description
Content-Type	Kötelező. Állítsa a következőre: `application/json`
api-key	Nem kötelező , ha Azure-szerepköröket használ, és egy tulajdonosi jogkivonatot ad meg a kéréshez, ellenkező esetben kulcsra van szükség. A létrehozási kérelmeknek tartalmazniuk kell egy `api-key` , a rendszergazdai kulcsra beállított fejlécet (a lekérdezési kulcs helyett). A részletekért lásd: Csatlakozás az Azure AI Search szolgáltatáshoz kulcshitelesítés használatával .

Kérelem törzse

A kérelem törzse tartalmaz egy adatforrás-definíciót, amely tartalmazza az adatforrás típusát, az adatok olvasásához szükséges hitelesítő adatokat, valamint egy választható adatváltozás-észlelési és adattörlési észlelési szabályzatot, amelyek az adatforrásban lévő módosított vagy törölt adatok hatékony azonosítására szolgálnak, ha rendszeres időközönként ütemezett indexelővel használják őket.

A következő JSON a definíció fő részeinek magas szintű ábrázolása.

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

A kérelem a következő tulajdonságokat tartalmazza:

Tulajdonság	Leírás
name	Kötelező. Az adatforrás neve. Az adatforrás nevének csak kisbetűket, számjegyeket vagy kötőjeleket kell tartalmaznia, nem indítható el és nem végződhet kötőjelekkel, és legfeljebb 128 karakter hosszúságú lehet.
leírás	Nem kötelező leírás.
típus	Kötelező. Az egyik támogatott adatforrástípusnak kell lennie: `azuresql` Azure SQL Database esetén Azure SQL Managed Instance vagy SQL Server-példány fut az Azure-beli virtuális gépen `cosmosdb` az Azure Cosmos DB for NoSQL-hez, az Azure Cosmos DB for MongoDB -hez (előzetes verzió) vagy az Azure Cosmos DB for Apache Gremlinhez (előzetes verzió) `azureblob`Azure Blob Storage `adlsgen2` az Azure Table Storage `azurefile`Azure Data Lake Storage Gen2 `azuretable` Azure Files -hez (előzetes verzió) `mysql`Azure Database for MySQL ( előzetes verzió) `sharepoint` a SharePointhoz a Microsoft 365-ben (előzetes verzió)
hitelesítő adatok	Kötelező. Tartalmaz egy `connectionString` tulajdonságot, amely meghatározza az adatforrás kapcsolati karakterlánc. A kapcsolati karakterlánc formátuma az adatforrás típusától függ: Azure SQL Database esetében ez a szokásos SQL Server kapcsolati karakterlánc. Ha Azure Portal használ a kapcsolati karakterlánc lekéréséhez, válassza a `ADO.NET connection string` lehetőséget. Az Azure Cosmos DB esetében a kapcsolati karakterlánc a következő formátumban kell lennie: `"AccountEndpoint=https://[your account name].documents.azure.com;AccountKey=[your account key];Database=[your database id]"`. Az összes értékre szükség van. Ezeket a Azure Portal találja meg. A Azure Blob Storage esetében a kapcsolati karakterlánc formátumokat a Blob indexelés konfigurálása az Azure AI Searchben című cikk Hitelesítő adatok szakaszában definiáljuk. Az Azure Storage, a Azure SQL Database és az Azure Cosmos DB olyan felügyelt identitásokat is támogat kapcsolati karakterlánc, amelyek nem tartalmaznak fiókkulcsot a kapcsolati karakterlánc. A felügyelt identitás kapcsolati karakterlánc formátumának használatához kövesse az indexelők adatforráshoz való csatlakozásának beállítása felügyelt identitással című témakör utasításait. Ha frissíti az adatforrást, a kapcsolati karakterlánc nem szükséges. Az értékek`<unchanged>`, vagy `<redacted>` a tényleges kapcsolati karakterlánc helyett használhatók.
tároló	Kötelező. Megadja az indexelendő adatokat a (kötelező) és a `name` (nem kötelező) tulajdonságok használatával:`name` : A Azure SQL a táblát vagy a nézetet adja meg.`query` A séma által minősített neveket használhatja, például `[dbo].[mytable]`: . Az Azure Cosmos DB esetében az SQL API-gyűjteményt adja meg. A Azure Blob Storage a tárolót adja meg. Az Azure Table Storage esetében a tábla nevét adja meg. `query`: Az Azure Cosmos DB-hez megadhat egy lekérdezést, amely egy tetszőleges JSON-dokumentumelrendezést simít egy olyan sima sémába, amelyet az Azure AI Search indexelhet. A Azure Blob Storage lehetővé teszi egy virtuális mappa megadását a blobtárolón belül. Blob elérési útja `mycontainer/documents/blob.pdfdocuments` például virtuális mappaként használható. Az Azure Table Storage esetében megadhat egy lekérdezést, amely szűri az importálni kívánt sorok készletét. A Azure SQL esetében a lekérdezés nem támogatott. Használjon inkább nézeteket.
dataChangeDetectionPolicy	Választható. A módosított adatelemek azonosítására szolgál. A támogatott szabályzatok az adatforrás típusától függően változnak. Az érvényes szabályzatok a magas vízjeles változásészlelési szabályzat és az SQL integrált változásészlelési szabályzata. A magas vízjelváltozás-észlelési szabályzat egy meglévő oszloptól vagy tulajdonságtól függ, amely más frissítésekkel együtt frissül (minden beszúrás a vízjel oszlopának frissítését eredményezi), és az érték változása magasabb. Cosmos DB-adatforrások esetén a tulajdonságot `_ts` kell használnia. A Azure SQL esetében az indexelt `rowversion` oszlop az ideális választás a magas vízjel-szabályzattal való használatra. Az Azure Storage esetében a változásészlelés a lastModified értékek használatával beépített, így nincs szükség a blob- vagy táblatároló dataChangeDetectionPolicy beállítására. Az SQL integrált változásészlelési szabályzata az SQL Server natív változásészlelési funkcióira hivatkozik. Ez a szabályzat csak táblákkal használható; a nézetekkel nem használható. A szabályzat használata előtt engedélyeznie kell a változáskövetést a használt táblához. Útmutatásért lásd: Változáskövetés engedélyezése és letiltása . Az indexelő változásészlelési támogatásával kapcsolatos további információkért lásd: Csatlakozás Azure SQL tartalomhoz és indexelés.
dataDeletionDetectionPolicy	Választható. A törölt adatelemek azonosítására szolgál. Jelenleg az egyetlen támogatott szabályzat a helyreállítható törlési szabályzat, amely az adatforrás "helyreállítható törlés" oszlopának vagy tulajdonságának értéke alapján azonosítja a törölt elemeket. Csak a sztringgel, egész számmal vagy logikai értékekkel rendelkező oszlopok támogatottak. A használt `softDeleteMarkerValue` értéknek sztringnek kell lennie, még akkor is, ha a megfelelő oszlop egész számokat vagy logikai értékeket tartalmaz. Ha például az adatforrásban megjelenő érték 1, használja az "1" értéket.`softDeleteMarkerValue`
encryptionKey	Választható. Az inaktív adatforrás titkosítására szolgál a saját kulcsaival, amelyeket az Azure Key Vault kezel. A 2019-01-01-en vagy azt követően létrehozott számlázható keresési szolgáltatásokhoz érhető el. A `encryptionKey` szakasz tartalmaz egy felhasználó által definiált `keyVaultKeyName` (kötelező), egy rendszer által létrehozott `keyVaultKeyVersion` (kötelező) és egy `keyVaultUri` kulcsot (kötelező, más néven DNS-nevet). Példa URI-ra: "https://my-keyvault-name.vault.azure.net". Igény szerint megadhatja `accessCredentials` , hogy nem felügyelt rendszeridentitást használ-e. `accessCredentials` A következők `applicationId` tulajdonságai: (Microsoft Entra ID alkalmazásazonosító, amely hozzáférési engedélyeket kapott a megadott Azure-Key Vault) és `applicationSecret` (a regisztrált alkalmazás hitelesítési kulcsa). A következő szakaszban egy példa szemlélteti a szintaxist.

Reagálás

Sikeres kérés esetén: 201 Létrehozva.

Példák

Példa: Azure SQL változásészleléssel (magas vízjeles változásészlelési szabályzat)

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

Példa: változásészlelési Azure SQL (SQL Integrated Change Tracking Policy)

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

Példa: Azure SQL törlésészleléssel rendelkező változásészleléssel

Ne feledje, hogy a törlésészlelési tulajdonságok a és softDeleteMarkerValueasoftDeleteColumnName.

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

Példa: Adatforrás csak kötelező tulajdonságokkal

A változás- és törlésészleléshez kapcsolódó választható tulajdonságok elhagyhatók, ha csak az adatforrást szeretné használni az adatok egyszeri másolatához:

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

Példa: Hitelesítő adatok kihagyása

Ha frissíteni szeretné az adatforrást, a hitelesítő adatokra nincs szükség. Az értékek<unchanged>, vagy <redacted> használhatók a kapcsolati karakterlánc helyett.

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

Példa: Titkosítási kulcsok

A titkosítási kulcsok az ügyfél által felügyelt kulcsok, amelyeket a további titkosításhoz használnak. További információ: Titkosítás ügyfél által felügyelt kulcsokkal az 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)"}
      }
}