wtyczka cosmosdb_sql_request

Artykuł
10/15/2024

Dotyczy: ✅Microsoft Fabric ✅Azure Data Explorer✅Azure Monitor ✅Microsoft Sentinel

Wtyczka cosmosdb_sql_request wysyła zapytanie SQL do punktu końcowego sieci SQL usługi Azure Cosmos DB i zwraca wyniki zapytania. Ta wtyczka jest przeznaczona głównie do wykonywania zapytań dotyczących małych zestawów danych, na przykład wzbogacania danych przy użyciu danych referencyjnych przechowywanych w usłudze Azure Cosmos DB. Wtyczka jest wywoływana z operatorem evaluate .

Składnia

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

Dowiedz się więcej na temat konwencji składni.

Parametry

Nazwisko	Type	Wymagania	opis
ConnectionString	`string`	✔️	Parametry połączenia wskazująca kolekcję usługi Azure Cosmos DB na zapytanie. Musi zawierać pozycje AccountEndpoint, Database i Collection. Może zawierać wartość AccountKey , jeśli klucz główny jest używany do uwierzytelniania. Aby uzyskać więcej informacji, zobacz Uwierzytelnianie i autoryzacja. Przykład: `'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>'`
Zapytanie sql	`string`	✔️	Zapytanie do wykonania.
Parametry sql	`dynamic`		Obiekt torby właściwości do przekazania jako parametry wraz z zapytaniem. Nazwy parametrów muszą zaczynać się od `@`.
OutputSchema			Nazwy i typy oczekiwanych kolumn danych wyjściowych `cosmosdb_sql_request` wtyczki. Użyj następującej składni: `(` ColumnName `:` ColumnType [`,` ...] `)`. Określenie tego parametru umożliwia wiele optymalizacji zapytań.
Opcje	`dynamic`		Obiekt torby właściwości ustawień zaawansowanych. Jeśli parametr `AccountKey` nie jest podany w parametrze ConnectionString, `armResourceId` wymagane jest pole tego parametru. Aby uzyskać więcej informacji, zobacz Obsługiwane opcje.

Obsługiwane opcje

W poniższej tabeli opisano obsługiwane pola parametru Opcje .

Nazwisko	Pisz	Opis
`armResourceId`	`string`	Identyfikator zasobu usługi Azure Resource Manager bazy danych Cosmos DB. Jeśli klucz konta nie jest podany w argumencie parametry połączenia, to pole jest wymagane. W takim przypadku `armResourceId` element jest używany do uwierzytelniania w usłudze Cosmos DB. Przykład: `armResourceId='/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'`
`token`	`string`	Token dostępu firmy Microsoft Entra podmiotu zabezpieczeń z dostępem do bazy danych Cosmos DB. Ten token jest używany wraz z elementem `armResourceId` do uwierzytelniania w usłudze Azure Resource Manager. Jeśli nie określono, token podmiotu zabezpieczeń, który wykonał zapytanie, jest używany. Jeśli `armResourceId` nie zostanie określony, token jest używany bezpośrednio do uzyskiwania dostępu do bazy danych Cosmos DB. Aby uzyskać więcej informacji na temat metody uwierzytelniania tokenu, zobacz Uwierzytelnianie i autoryzacja.
`preferredLocations`	`string`	Region, z którego chcesz wykonywać zapytania dotyczące danych. Przykład: `['East US']`

Uwierzytelnianie i autoryzacja

Aby autoryzować punkt końcowy sieci SQL usługi Azure Cosmos DB, należy określić informacje o autoryzacji. Poniższa tabela zawiera obsługiwane metody uwierzytelniania oraz opis sposobu używania tej metody.

Metoda uwierzytelniania	opis
Tożsamość zarządzana (zalecane)	Dołącz `Authentication="Active Directory Managed Identity";User Id={object_id};` do parametry połączenia. Żądanie jest wykonywane w imieniu tożsamości zarządzanej, która musi mieć odpowiednie uprawnienia do bazy danych. Aby włączyć uwierzytelnianie tożsamości zarządzanej, należy dodać tożsamość zarządzaną do klastra i zmienić zasady tożsamości zarządzanej. Aby uzyskać więcej informacji, zobacz Zasady tożsamości zarządzanej.
Identyfikator zasobu usługi Azure Resource Manager	Ta metoda uwierzytelniania wymaga określenia parametru `armResourceId` i opcjonalnie `token` w opcjach. Element `armResourceId` identyfikuje konto bazy danych usługi Cosmos DB i `token` musi być prawidłowym tokenem elementu nośnego Firmy Microsoft dla podmiotu z uprawnieniami dostępu do bazy danych Cosmos DB. Jeśli nie `token` zostanie podany, token entra firmy Microsoft żądania podmiotu zabezpieczeń będzie używany do uwierzytelniania.
Klucz konta	Klucz konta można dodać bezpośrednio do argumentu ConnectionString . Jednak takie podejście jest mniej bezpieczne, ponieważ obejmuje dołączenie wpisu tajnego w tekście zapytania i jest mniej odporne na przyszłe zmiany klucza konta. Aby zwiększyć bezpieczeństwo, ukryj wpis tajny jako zaciemniony literał ciągu.
Token	Wartość tokenu można dodać w opcjach wtyczki. Token musi należeć do podmiotu zabezpieczeń z odpowiednimi uprawnieniami. Aby zwiększyć bezpieczeństwo, ukryj token jako zaciemniony literał ciągu.

Ustawianie zasad objaśnienie

Wtyczka wywołuje wystąpienie usługi Azure Cosmos DB. Upewnij się, że zasady objaśnienia klastra umożliwiają wywołania typu cosmosdb do docelowego identyfikatora CosmosDbUri.

W poniższym przykładzie pokazano, jak zdefiniować zasady objaśnienie dla usługi Azure Cosmos DB. Zaleca się ograniczenie go do określonych punktów końcowych (my_endpoint1, my_endpoint2).

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

W poniższym przykładzie pokazano polecenie alter callout policy dla cosmosdb calloutType

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

Przykłady

W poniższych przykładach użyto tekstu zastępczego w nawiasach kwadratowych.

Wykonywanie zapytań względem usługi Azure Cosmos DB przy użyciu schematu danych wyjściowych zdefiniowanych przez zapytanie

W poniższym przykładzie użyto wtyczki cosmosdb_sql_request do wysyłania zapytania SQL podczas wybierania tylko określonych kolumn. To zapytanie używa jawnych definicji schematu, które umożliwiają różne optymalizacje przed uruchomieniem rzeczywistego zapytania względem usługi Cosmos DB.

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

Wykonywanie zapytań do bazy danych Azure Cosmos DB

W poniższym przykładzie użyto wtyczki cosmosdb_sql_request , aby wysłać zapytanie SQL w celu pobrania danych z usługi Azure Cosmos DB przy użyciu usługi Azure Cosmos DB dla NoSQL.

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

Wykonywanie zapytań względem usługi Azure Cosmos DB przy użyciu parametrów

W poniższym przykładzie użyto parametrów zapytania SQL i wykonuje zapytania dotyczące danych z regionu alternatywnego. Aby uzyskać więcej informacji, zobacz preferredLocations.

evaluate cosmosdb_sql_request(
   'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "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'

Wykonywanie zapytań względem usługi Azure Cosmos DB i dołączanie danych za pomocą tabeli bazy danych

Poniższy przykład łączy dane partnerów z usługi Azure Cosmos DB z danymi partnerskimi w bazie danych przy użyciu Partner pola . Powoduje to wyświetlenie listy partnerów ze swoimi numerami telefonów, witryną internetową i kontaktowym adresem e-mail posortowaną według nazwy partnera.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;AccountKey='h'<AccountKey>',
    "SELECT c.id, c.Partner, c. phoneNumber FROM c') : (Id:long, Partner:string, phoneNumber:string) 
| join kind=innerunique Partner on Partner
| project id, Partner, phoneNumber, website, Contact
| sort by Partner

Wykonywanie zapytań względem usługi Azure Cosmos DB przy użyciu uwierzytelniania tokenu

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic(null),
    dynamic({'token': h'abc123...'})
) : (Id:long, Name:string, City:string)

Wykonywanie zapytań dotyczących usługi Azure Cosmos DB przy użyciu identyfikatora zasobu usługi Azure Resource Manager na potrzeby uwierzytelniania

W poniższym przykładzie użyto identyfikatora zasobu usługi Azure Resource Manager do uwierzytelniania i tokenu Entra firmy Microsoft podmiotu zabezpieczeń żądającego, ponieważ nie określono tokenu. Wysyła zapytanie SQL podczas wybierania tylko określonych kolumn i określa jawne definicje schematu.

evaluate cosmosdb_sql_request(
    'AccountEndpoint=https://cosmosdbacc.documents.azure.com/;Database=<MyDatabase>;Collection=<MyCollection>;',
    "SELECT c.Id, c.Name, c.City FROM c",
    dynamic({'armResourceId': '/subscriptions/<SubscriptionId>/resourceGroups/<ResourceGroup>/providers/Microsoft.DocumentDb/databaseAccounts/<DatabaseAccount>'})
) : (Id:long, Name:string, City:string)

Udostępnij za pośrednictwem