cosmosdb_sql_request plugin

A cosmosdb_sql_request beépülő modul SQL-lekérdezést küld egy Azure Cosmos DB SQL-hálózati végpontnak, és visszaadja a lekérdezés eredményeit. Ez a beépülő modul elsősorban kis adathalmazok lekérdezésére szolgál, például az Azure Cosmos DB-ben tárolt referenciaadatokkal való bővítésre. A beépülő modul meghívása az evaluate operátorral történik.

Syntax

evaluatecosmosdb_sql_request(ConnectionString,SqlQuery [,SqlParameters [,Options]] ) [:OutputSchema]

További információ a szintaxis konvenciókról.

Paraméterek

Név	Típus	Kötelező	Leírás
ConnectionString	string	✔️	A lekérdezendő Azure Cosmos DB-gyűjteményre mutató kapcsolati karakterlánc. Tartalmaznia kell az AccountEndpointot, az Adatbázist és a Gyűjteményt. Az AccountKey is lehet, ha a hitelesítéshez főkulcsot használnak. További információ: Hitelesítés és engedélyezés. Példa:'AccountEndpoint=https://cosmosdbacc.documents.azure.com/ ;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;'
SqlQuery	string	✔️	A végrehajtandó lekérdezés.
SqlParameters	dynamic		A paraméterként átadni kívánt tulajdonságcsomag-objektum a lekérdezéssel együtt. A paraméterneveknek a kezdetével kell kezdődniük @.
OutputSchema			A beépülő modul kimenetének várt oszlopainak cosmosdb_sql_request nevei és típusai. Használja a következő szintaxist: (ColumnName:ColumnType [, ...] ). A paraméter megadása több lekérdezésoptimalizálást is lehetővé tesz.
Beállítások	dynamic		Speciális beállítások tulajdonságcsomag-objektuma. AccountKey Ha egy nincs megadva a ConnectionStringben, akkor ennek a paraméternek a armResourceId mezőjére van szükség. További információ: Támogatott beállítások.

Támogatott beállítások

Az alábbi táblázat a Beállítások paraméter támogatott mezőit ismerteti.

Név	Típus	Description
armResourceId	string	Az Azure Resource Manager Cosmos DB-adatbázis erőforrás-azonosítója. Ha a kapcsolati karakterlánc argumentumban nincs megadva fiókkulcs, akkor erre a mezőre van szükség. Ilyen esetben a armResourceId a használatával hitelesíthető a Cosmos DB-ben. Példa:/subscriptions/a0cd6542-7eaf-43d2-bbdd-b678a869aad1/resourceGroups/ cosmoddbresourcegrouput/providers/Microsoft.DocumentDb/databaseAccounts/cosmosdbacc
token	string	A Cosmos DB-adatbázishoz hozzáféréssel rendelkező rendszerbiztonsági tag Microsoft Entra hozzáférési jogkivonata. Ezt a jogkivonatot a rendszer a-val armResourceId együtt használja az Azure Resource Manager való hitelesítéshez. Ha nincs meghatározva, a rendszer a lekérdezést végrehajtott rendszerbiztonsági tag jogkivonatát használja.
preferredLocations	string	Az a régió, amelyből le szeretné kérdezni az adatokat. Példa:['East US']

Hitelesítés és engedélyezés

Az Azure Cosmos DB SQL-hálózati végpontra való engedélyezéshez meg kell adnia az engedélyezési adatokat. Az alábbi táblázat a támogatott hitelesítési módszereket és a metódus használatának leírását tartalmazza.

Hitelesítési módszer	Description
Azure Resource Manager erőforrás-azonosítója (ajánlott)	A biztonságos hitelesítés érdekében javasoljuk, hogy adja meg a armResourceId és a token értéket a beállítások között. A armResourceId azonosítja a Cosmos DB-adatbázisfiókot, és a-nak token érvényes Microsoft Entra tulajdonosi jogkivonatnak kell lennie a Cosmos DB-adatbázishoz hozzáférési engedélyekkel rendelkező rendszerbiztonsági tag számára. Ha nincs token megadva, a rendszer a kérés résztvevőjének Microsoft Entra jogkivonatát fogja használni a hitelesítéshez.
Fiókkulcs	A fiókkulcsot közvetlenül is hozzáadhatja a ConnectionString argumentumhoz. Ez a megközelítés azonban kevésbé biztonságos, mivel magában foglalja a titkos kulcsot a lekérdezés szövegében, és kevésbé rugalmas a fiókkulcs jövőbeli változásaival szemben. A biztonság növelése érdekében rejtse el a titkos kódot rejtett sztringkonstansként.

Ábrafelirat-szabályzat beállítása

A beépülő modul feliratokat készít az Azure Cosmos DB-példányhoz. Győződjön meg arról, hogy a fürt feliratszabályzata engedélyezi a cél CosmosDbUri típusú cosmosdb hívásokat.

Az alábbi példa bemutatja, hogyan definiálhatja az Azure Cosmos DB-hez tartozó ábrafelirat-szabályzatot. Ajánlott adott végpontokra (my_endpoint1, my_endpoint2) korlátozni.

[
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint1\\.documents\\.azure\\.com",
    "CanCall": true
  },
  {
    "CalloutType": "CosmosDB",
    "CalloutUriRegex": "my_endpoint2\\.documents\\.azure\\.com",
    "CanCall": true
  }
]

Az alábbi példa egy ábrafeliratszabályzat-parancsot mutat be a CalloutType-hozcosmosdb

.alter cluster policy callout @'[{"CalloutType": "cosmosdb", "CalloutUriRegex": "\\.documents\\.azure\\.com", "CanCall": true}]'

Példák

Az Azure Cosmos DB lekérdezése lekérdezéssel definiált kimeneti sémával

Az alábbi példa a cosmosdb_sql_request beépülő modult használja sql-lekérdezések küldésére, miközben csak bizonyos oszlopokat választ ki. Ez a lekérdezés explicit sémadefiníciókat használ, amelyek lehetővé teszik a különböző optimalizálásokat a tényleges lekérdezés Cosmos DB-vel való futtatása előtt.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
  'SELECT c.Id, c.Name from c') : (Id:long, Name:string) 

Az Azure Cosmos DB lekérdezése

Az alábbi példa a cosmosdb_sql_request beépülő modult használja egy SQL-lekérdezés küldéséhez, amely adatokat kér le az Azure Cosmos DB-ből a NoSQL-hez készült Azure Cosmos DB használatával.

evaluate cosmosdb_sql_request(
  'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
  'SELECT * from c') // OutputSchema is unknown, so it is not specified. This may harm the performance of the query.

Azure Cosmos DB lekérdezése paraméterekkel

Az alábbi példa SQL-lekérdezési paramétereket használ, és egy másik régióból kérdezi le az adatokat. További információ: preferredLocations.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=MyDatabase;Collection=MyCollection;AccountKey=' h'R8PM...;',
    "SELECT c.id, c.lastName, @param0 as Column0 FROM c WHERE c.dob >= '1970-01-01T00:00:00Z'",
    dynamic({'@param0': datetime(2019-04-16 16:47:26.7423305)}),
    dynamic({'preferredLocations': ['East US']})) : (Id:long, Name:string, Column0: datetime) 
| where lastName == 'Smith'

Ez a képesség nem támogatott az Azure Monitorban