Azure Cosmos DB Verbindungsdetails

Einführung

Connector-Version

Diese Dokumentation basiert auf Version 23.0.8895 des Connectors.

Erste Schritte

Versionsunterstützung für Azure Cosmos DB

Der Connector ermöglicht einen standardbasierten Zugriff auf Azure Cosmos DB.

Herstellen einer Verbindung

Vor dem Anschließen

Rollenzuweisung

Stellen Sie sicher, dass die Azure-Identität die richtige Rolle hat. Die Identität ist das Konto, mit dem Sie sich während der Microsoft Entra ID Authentifizierung beim Browser anmelden, oder die Anwendung selbst für AzureServicePrincipal.

Authentifizierung. Weitere Einzelheiten finden Sie unter folgendem Link:

Konfigurieren Sie die rollenbasierte Zugriffssteuerung für Ihr Azure Cosmos DB Konto mit Entra ID

Sie können entweder eine der integrierten Rolle zuweisen:

• Integrierter Datenleser von CosmosDB
• Integrierter Datenbeitragender von CosmosDB

oder erstellen Sie Ihre eigenen benutzerdefinierten Rolle. Sie müssen auch den Umfang der Rolle festlegen, wobei "/" bedeutet, dass die Identität Zugriff auf alle Datenbanken hat.

Herstellen einer Verbindung mit Azure Cosmos DB

Kontoschlüssel

Melden Sie sich beim Azure-Portal an und wählen Sie Azure Cosmos DB, und wählen Sie Ihr Konto aus.

Legen Sie zur Authentifizierung Folgendes fest:

• AccountEndpoint: Die Cosmos DB-Konto URL. Legen Sie diese auf fest URI Wert gefunden in Settings > Keys Blade des Cosmos DB-Kontos.
• AccountKey: Ein Hauptschlüsseltoken oder ein Ressourcentoken für die Verbindung mit Azure Cosmos DB. Legen Sie dies auf fest PRIMARY KEY Wert gefunden in Settings > Keys Blade des Cosmos DB-Kontos.
• TokenType: (optional). Setzen Sie dies auf „Master“ (Standardwert), wenn Sie ein Master-Token verwenden, also ein vollständiges Berechtigungstoken, das bei der Kontoerstellung generiert wird. Andernfalls setzen Sie diese Eigenschaft auf „Ressource“, wenn Sie ein Ressourcentoken verwenden, also ein benutzerdefiniertes Berechtigungstoken, das bei der Einrichtung eines Datenbankbenutzers generiert wird.

Microsoft Entra ID

Microsoft Entra ID ist der mehrinstanzenfähige, cloudbasierte Verzeichnis- und Identitätsverwaltungsdienst von Microsoft. Es handelt sich um eine benutzerbasierte Authentifizierung, für die Sie Folgendes festlegen müssen: AuthScheme Zu AzureAD.

Die Authentifizierung bei Microsoft Entra ID über eine Webanwendung erfordert immer die Erstellung einer benutzerdefinierten OAuth-Anwendung. Weitere Informationen finden Sie unter Erstellen einer Entra ID-Anwendung.

Desktop-Anwendungen

bietet eine eingebettete OAuth-Anwendung, die die Verbindung zu Microsoft Entra ID von einer Desktop-Anwendung aus vereinfacht.

Sie können sich auch von einer Desktop-Anwendung aus mit einer benutzerdefinierten OAuth-Anwendung authentifizieren. (Weitere Informationen finden Sie unter Erstellen einer Entra ID-Anwendung.) Um sich über die Entra-ID zu authentifizieren, legen Sie diese Parameter fest:

• AuthScheme: AzureAD.
• Nur benutzerdefinierte Anwendungen:
  • OAuthClientId: Die Client-ID, die Ihnen bei der Registrierung Ihrer benutzerdefinierten OAuth-Anwendung zugewiesen wurde.
  • OAuthClientSecret: Das Client-Geheimnis, das Ihnen bei der Registrierung Ihrer benutzerdefinierten OAuth-Anwendung zugewiesen wurde.
  • CallbackURL: Die Umleitungs-URI, die Sie bei der Registrierung Ihrer benutzerdefinierten OAuth-Anwendung definiert haben.

Wenn Sie eine Verbindung herstellen, öffnet der Connector den OAuth-Endpoint von Azure Cosmos DB in Ihrem Standardbrowser. Melden Sie sich an und erteilen Sie der Anwendung Berechtigungen.

Der Connector schließt den OAuth-Prozess ab, erhält ein Zugriffstoken von Azure Cosmos DB und verwendet es zum Anfordern von Daten. Die OAuth-Werte werden in dem in angegebenen Pfad gespeichert OAuthSettingsLocation. Diese Werte bleiben über Verbindungen hinweg bestehen.

Wenn das Zugriffstoken abläuft, aktualisiert der Connector es automatisch.

Microsoft Entra-Dienstprinzipal

Azure Service Principal ist eine rollenbasierte, anwendungsbasierte Authentifizierung. Das bedeutet, dass die Authentifizierung pro Anwendung und nicht pro Benutzer erfolgt. Alle von der Anwendung übernommenen Aufgaben werden ohne Standardbenutzerkontext, sondern basierend auf den zugewiesenen Rollen ausgeführt. Der Anwendungszugriff auf die Ressourcen wird über die Berechtigungen der zugewiesenen Rollen gesteuert.

Informationen zum Einrichten der Microsoft Entra-Dienstprinzipalauthentifizierung finden Sie unter Erstellen einer Entra-ID-Anwendung mit Dienstprinzipal.

Erstellen einer Entra-ID-Anwendung

Erstellen einer Entra-ID-Anwendung

Azure Cosmos DB unterstützt benutzerbasierte Authentifizierung mit Entra ID. Diese Authentifizierung ist OAuth-basiert.

Um eine Verbindung mit Azure Cosmos DB über das Web herzustellen, müssen Sie immer eine benutzerdefinierte Anwendung erstellen, wie hier beschrieben.

Benutzerdefinierte OAuth-Anwendungen sind nützlich, wenn Sie:

• Kontrollieren Sie das Branding des Authentifizierungsdialogs.
• Steuern Sie die Umleitungs-URI, zu der die Anwendung den Benutzer nach seiner Authentifizierung umleitet.
• Passen Sie die Berechtigungen an, die Sie vom Benutzer anfordern.

Authentifizieren mit Entra-ID

In <https://portal.azure.com>:

1. Wählen Sie im linken Navigationsbereich Microsoft Entra ID > App registrations.

2. Klicken Sie auf New registration.

3. Geben Sie einen Namen für die Anwendung ein.

4. Geben Sie die Kontotypen an, die diese Anwendung unterstützen soll:

   • Für Anwendungen zur privaten Nutzung wählen Sie Accounts in this organization directory only.
   • Für verteilte Anwendungen wählen Sie eine der Multi-Tenant-Optionen.

1. Setzen Sie die Umleitungs-URI auf http://localhost:33333 (Standard) ODER, wenn Sie möchten

   anderen Port angeben, gewünschten Port angeben und einstellen CallbackURL zur genauen Antwort URL, die Sie gerade definiert haben.

2. Um die neue Anwendung zu registrieren, klicken Sie auf Register. Ein Anwendungsverwaltungsbildschirm wird angezeigt. Notieren Sie diese Werte zur späteren Verwendung. (Sie verwenden die Application (client) IDWert zum Festlegen von OAuthClientId Parameter und die Directory (tenant) IDWert zum Festlegen von AzureTenant Parameter.)

3. Navigieren Sie zu Certificates & Secrets. Wählen New Client Secret für diese Anwendung und geben Sie die gewünschte Dauer an. Nachdem das Clientgeheimnis gespeichert wurde, zeigt die Azure App-Registrierung den Schlüsselwert an. Dieser Wert wird nur einmal angezeigt, notieren Sie ihn also für die zukünftige Verwendung. (Sie werden ihn verwenden, um den festzulegen OAuthClientSecret.)

4. Wenn Sie die Verwendung von Berechtigungen angegeben haben, für die die Zustimmung des Administrators erforderlich ist (z. B. Anwendungsberechtigungen), können Sie diese vom aktuellen Mandanten aus auf der Seite „API Berechtigungen“ erteilen.

Erstellen einer Entra-ID-Anwendung mit Service Principal

Erstellen einer Entra-ID-Anwendung mit Service Principal

Azure Cosmos DB unterstützt die rollenbasierte Authentifizierung auf Basis des Dienstprinzipals. Wenn Sie einen Dienstprinzipal zur Authentifizierung bei Azure Cosmos DB verwenden möchten, müssen Sie eine benutzerdefinierte Microsoft Entra ID Anwendung erstellen, wie hier beschrieben. Um die Microsoft Entra-Dienstprinzipalauthentifizierung zu verwenden, müssen Sie die Möglichkeit einrichten, der Authentifizierungsanwendung eine Rolle zuzuweisen. Anschließend müssen Sie eine Anwendung beim Microsoft Entra ID Mandanten registrieren, um einen neuen Dienstprinzipal zu erstellen. Dieser neue Dienstprinzipal kann dann die zugewiesene rollenbasierte Zugriffssteuerung nutzen, um auf Ressourcen in Ihrem Abonnement zuzugreifen.

Authentifizieren mit einem Microsoft Entra-Dienstprinzipal

In <https://portal.azure.com>:

1. Wählen Sie im linken Navigationsbereich Microsoft Entra ID > App registrations.
2. Klicken Sie auf New registration.
3. Geben Sie einen Namen für die Anwendung ein.
4. Wählen Sie die gewünschte Mandantenkonfiguration aus. Da diese benutzerdefinierte Anwendung für den Microsoft Entra-Dienstprinzipal bestimmt ist, wählen Sie Any Microsoft Entra ID tenant - Multi Tenant.
5. Um die neue Anwendung zu registrieren, klicken Sie auf Register. Ein Anwendungsverwaltungsbildschirm wird angezeigt.
   Notieren Sie den Wert in Application (client) ID als OAuthClientId und das Directory (tenant) ID als AzureTenant.
6. Navigieren Sie zu Certificates & Secrets und definieren Sie den Authentifizierungstyp der Anwendung. Es stehen zwei Arten der Authentifizierung zur Verfügung: Zertifikat (empfohlen) oder Client-Geheimnis.
   • Für die Zertifikatsauthentifizierung: In Certificates & Secrets, wählen Upload certificate, und laden Sie dann das Zertifikat von Ihrem lokalen Computer hoch. Ein Beispiel zum Erstellen dieses Zertifikats finden Sie unter https://learn.microsoft.com/en-us/entra/identity-platform/howto-create-self-signed-certificate.
   • Zum Erstellen eines neuen Client-Geheimnisses: In Certificates & Secrets, wählen New Client Secret für die Anwendung und geben Sie deren Dauer an. Nachdem der geheime Clientschlüssel gespeichert wurde, zeigt Azure Cosmos DB den Schlüsselwert an. Dieser Wert wird nur einmal angezeigt. Notieren Sie ihn daher für die zukünftige Verwendung. (Dieser Wert wird zum OAuthClientSecret.)
7. Navigieren Sie zur Tab Authentifizierung und wählen Sie die Access tokens Option.
8. Speichern Sie Ihre Änderungen.

Zustimmung zu Kundenanmeldeinformationen

OAuth unterstützt die Verwendung von Clientanmeldeinformationen zur Authentifizierung. In einem Clientanmeldeinformationen-Authentifizierungsablauf werden Anmeldeinformationen für die authentifizierende Anwendung selbst erstellt. Der Authentifizierungsablauf funktioniert genau wie der übliche Authentifizierungsablauf, mit der Ausnahme, dass ein zugeordneter Benutzer nicht aufgefordert wird, Anmeldeinformationen anzugeben.

Alle von der Anwendung akzeptierten Aufgaben werden außerhalb des Kontexts eines Standardbenutzers ausgeführt.

Verwenden Sie sie in einem Clientauthentifizierungsablauf. Sie müssen immer eine benutzerdefinierte Microsoft Entra ID Anwendung erstellen, um Clientanmeldeinformationen verwenden zu können.

In <https://portal.azure.com>:

1. Erstellen Sie eine benutzerdefinierte Microsoft Entra ID Anwendung, wie oben beschrieben.
2. Navigieren Sie zu App Registrations.
3. Suchen Sie die Anwendung, die Sie gerade erstellt haben, und öffnen Sie API Permissions.
4. Wählen Sie die Microsoft Graph-Berechtigungen aus. Es gibt zwei verschiedene Berechtigungssätze: Delegiert und Anwendung.
5. Geben Sie für die Verwendung mit dem Dienstprinzipal an Application Berechtigungen.
6. Wählen Sie die Berechtigungen aus, die Sie für Ihre Integration benötigen.

Optimieren des Datenzugriffs

Optimieren des Datenzugriffs

Mithilfe der folgenden Eigenschaften können Sie eine bessere Kontrolle über die Azure Cosmos DB API Funktionen und die Strategien erlangen, die der Connector zu deren Anzeige verwendet:

• RowScanDepth: Diese Eigenschaft bestimmt die Anzahl der Zeilen, die beim Generieren von Tabellenmetadaten gescannt werden, um Spaltendatentypen zu erkennen.
• TypeDetectionScheme: Diese Eigenschaft ermöglicht mehr Kontrolle über die von implementierte Strategie RowScanDepth Eigentum.
• GenerateSchemaFiles: Mit dieser Eigenschaft können Sie Tabellenmetadaten in statischen Schema speichern, die leicht angepasst werden können, um beispielsweise Ihre Änderungen an Spaltendatentypen dauerhaft zu speichern.
  Sie können diese Eigenschaft auf „OnStart“ setzen, um bei der Verbindung Schema für alle Tabellen in Ihrer Datenbank zu generieren. Oder Sie können Schemas generieren, während Sie SELECT-Abfragen an Tabellen ausführen.
  Die resultierenden Schemas basieren auf den Verbindungseigenschaften, die Sie zur Konfiguration der Automatischen Schemaerkennung verwenden
  Um die resultierenden Schema zu verwenden, setzen Sie die Location-Eigenschaft für den Ordner, der die Schemata enthält.

Festlegen eines RU-Budgets für Batch-Schreibvorgänge

Genau wie in der SQL-Konformität beschrieben Der Connector unterstützt Charge CUD-Vorgänge (Erstellen, Aktualisieren, Löschen). Die Batchverarbeitung wird durch die gleichzeitige Ausgabe mehrerer Anforderungen erreicht. Obwohl diese Methode die Leistung für Schreibvorgänge erheblich verbessert, sind die Kosten dieser Vorgänge relativ hoch, sodass das Budget für Anforderungseinheiten (RU) pro Sekunde für einen bestimmten Container oder eine bestimmte Datenbank möglicherweise überschritten wird. Abhängig von Ihren Azure Cosmos DB Dienstkontingenten kann das Überschreiten der RU-Budgets zusätzliche Kosten verursachen oder sogar die Azure Cosmos DB Nutzung für andere Workloads vorübergehend drosseln oder unterbrechen.

Um eine Überschreitung des RU-Budgets pro Sekunde zu vermeiden, passt der Connector die Anzahl gleichzeitiger Anfragen pro Sekunde dynamisch an, je nach eingestelltem WriteThroughputBudget und die ständig angepassten durchschnittlichen RU-Kosten pro Kontoauszug. Der Benutzer kann die WriteThroughputBudget Verbindungseigenschaft, um das RU-Budget pro Sekunde zu definieren, das Charge-Schreibvorgänge nicht überschreiten sollten. Ein weiterer wichtiger Faktor bei Charge-Schreibvorgängen ist die MaxThreads Verbindungseigenschaft, die die maximale Anzahl gleichzeitiger Anfragen angibt. Bei Verwendung einer niedrigen MaxThreads-Wert, der Connector kann das verfügbare Budget möglicherweise nicht effizient nutzen.

Da die drosselung clientseitig angewendet wird, kann das Budget für RU/s in einigen Fällen relativ geringfügig überschritten werden. Zu diesen Fällen gehören das Einfügen, Aktualisieren und Löschen von Datensätzen mit sehr variabler Spaltenanzahl und Eingabewertlänge pro Spalte.

Wichtige Hinweise

Konfigurationsdateien und ihre Pfade

• Alle Verweise auf das Hinzufügen von Konfigurationsdateien und deren Pfaden beziehen sich auf Dateien und Speicherorte auf dem Jitterbit-Agenten, auf dem der Connector installiert ist. Diese Pfade sind je nach Agent und Operationssystem entsprechend anzupassen. Wenn mehrere Agenten in einer Agentengruppe verwendet werden, werden auf jedem Agenten identische Dateien benötigt.

NoSQL-Datenbank

Azure Cosmos DB ist eine schemalose Dokumentdatenbank, die hohe Leistung, Verfügbarkeit und Skalierbarkeit bietet. Diese Funktionen sind nicht unbedingt mit einer standardkonformen Abfrage wie SQL-92 inkompatibel. In diesem Abschnitt zeigen wir verschiedene Schemata, die der Connector bietet, um die Lücke zwischen relationalem SQL und einer Dokumentdatenbank zu schließen.

Arbeiten mit Azure Cosmos DB Objekten als Tabellen

Der Connector modelliert die schemalosen Azure Cosmos DB Objekte in relationale Tabellen und übersetzt SQL-Abfragen in Azure Cosmos DB Abfragen, um die angeforderten Daten abzurufen. Siehe Abfragezuordnung (SQL- API) für weitere Details dazu, wie verschiedene Azure Cosmos DB Vorgänge als SQL dargestellt werden.

Schemas automatisch erkennen

Die Automatische Schemaerkennung-Schema findet automatisch die Datentypen in einem Azure Cosmos DB Objekt, indem es eine konfigurierte Anzahl von Zeilen des Objekts scannt. Sie können verwenden RowScanDepth, FlattenArrays, Und FlattenObjects um die relationale Darstellung der Sammlungen in Azure Cosmos DB zu steuern. Sie können auch Freiformabfragen schreiben nicht an das Schema gebunden.

Schemata anpassen

Optional können Sie Benutzerdefinierte Schemadefinitionen, um die von Ihnen gewählte relationale Struktur auf ein Azure Cosmos DB Objekt zu projizieren. Auf diese Weise können Sie die von Ihnen gewählten Spaltennamen, deren Datentypen und den Speicherort ihrer Werte in der Sammlung definieren.

Satz GenerateSchemaFiles um die erkannten Schemata als einfache Konfigurationsdateien zu speichern, die leicht zu erweitern sind. Sie können Schemata für alle Sammlungen in der Datenbank oder für die Ergebnisse von SELECT-Abfragen beibehalten.

Einschränkungen des RawValue TypeDetectionScheme

Wenn das TypeDetectionScheme ist gesetzt auf RawValue, der Connector überträgt jedes Dokument als einzelnen aggregierten Wert in eine Spalte mit dem Namen „JsonData“, zusammen mit seiner Ressourcenkennung in die separate Primärschlüsselspalte. Die JSON-Dokumente werden nicht verarbeitet und daher werden die folgenden Funktionen mit dieser Konfiguration NICHT unterstützt.

• Automatische Schemaerkennung
• Freiformabfragen
• Vertikale Abflachung
• Integrierte SQL API Funktionen
• SQL API GROUP BY
• Fast alle serverseitig unterstützten Filter außer den mit der Ressourcenkennung erstellten WHERE-Klauselbedingungen.

Automatische Schemaerkennung

Der Connector leitet automatisch ein relationales Schema ab, indem er eine Reihe von Azure Cosmos DB Dokumenten in einer Sammlung überprüft. Sie können die RowScanDepth Eigenschaft, um die Anzahl der Dokumente zu definieren, die der Connector zu diesem Zweck scannt. Die während des Erkennungsprozesses identifizierten Spalten hängen von der ab FlattenArrays Und FlattenObjects Eigenschaften.

Objekte abflachen

Wenn FlattenObjects gesetzt ist, werden alle verschachtelten Objekte in eine Reihe von Spalten zusammengefasst. Betrachten Sie beispielsweise das folgende Dokument:

{
  id: 12,
  name: "Lohia Manufacturers Inc.",
  address: {street: "Main Street", city: "Chapel Hill", state: "NC"},
  offices: ["Chapel Hill", "London", "New York"],
  annual_revenue: 35,600,000
}

Dieses Dokument wird durch die folgenden Spalten dargestellt:

Wenn FlattenObjects nicht gesetzt ist, werden die Spalten address.street, address.city und address.state nicht aufgeteilt. Die Adressspalte vom Typ string stellt stattdessen das gesamte Objekt dar. Ihr Wert wäre {street: "Main Street", city: "Chapel Hill", state: "NC"}. Siehe JSON-Funktionen für weitere Details zum Arbeiten mit JSON-Aggregaten. Sie können das Trennzeichen im Spaltennamen von einem Punkt ändern, indem Sie SeparatorCharacter.

Arrays abflachen

Der FlattenArrays-Eigenschaft kann verwendet werden, um Array-Werte in eigene Spalten zu reduzieren. Dies wird nur für Arrays empfohlen, die voraussichtlich kurz sind, beispielsweise die folgenden Koordinaten:

"coord": [-73.856077, 40.848447 ]

Die FlattenArrays Eigenschaft kann auf 2 gesetzt werden, um das obige Array wie folgt darzustellen:

Andere unbegrenzte Arrays lassen Sie am besten so, wie sie sind, und teilen die Daten bei Bedarf mithilfe von JSON-Funktionen aus.

Freiformabfragen

Wie in Automatische Schemaerkennung besprochen, intuitive Tabellenschemas ermöglichen SQL-Zugriff auf unstrukturierte Azure Cosmos DB Daten. JSON-Funktionen ermöglichen Ihnen die Verwendung von JSON-Standardfunktionen, um Azure Cosmos DB Daten zusammenzufassen und Werte aus beliebigen verschachtelten Strukturen zu extrahieren. Benutzerdefinierte Schemadefinitionen ermöglichen Ihnen die Definition statischer Tabellen und geben Ihnen eine genauere Kontrolle über die relationale Ansicht Ihrer Daten. Sie können beispielsweise Schemata schreiben, die übergeordnete/untergeordnete Tabellen oder Fakten-/Dimensionstabellen definieren. Sie sind jedoch nicht auf diese Schemata beschränkt.

Nach dem Verbinden können Sie jede verschachtelte Struktur Abfrage, ohne die Daten zu reduzieren. Alle Beziehungen, auf die Sie mit zugreifen können FlattenArrays Und FlattenObjects kann auch mit einer Ad-hoc-SQL- Abfrage aufgerufen werden.

Betrachten wir ein Beispieldokument aus dem folgenden Restaurant-Datensatz:

{
  "address": {
    "building": "1007",
    "coord": [
      -73.856077,
      40.848447
    ],
    "street": "Morris Park Ave",
    "zipcode": "10462"
  },
  "borough": "Bronx",
  "cuisine": "Bakery",
  "grades": [
    {
      "grade": "A",
      "score": 2,
      "date": {
        "$date": "1393804800000"
      }
    },
    {
      "date": {
        "$date": "1378857600000"
      },
      "grade": "B",
      "score": 6
    },
    {
      "score": 10,
      "date": {
        "$date": "1358985600000"
      },
      "grade": "C"
    }
  ],
  "name": "Morris Park Bake Shop",
  "restaurant_id": "30075445"
}

Sie können auf jede verschachtelte Struktur in diesem Dokument als Spalte zugreifen. Verwenden Sie die Punktnotation, um zu den Werten zu gelangen, auf die Sie zugreifen möchten, wie in der folgenden Abfrage gezeigt. Beachten Sie, dass Arrays einen nullbasierten Index haben. Die folgende Abfrage ruft beispielsweise die zweite Klasse für das Restaurant im Beispiel ab:

SELECT [address.building],`[Noten.1.Klasse] `FROM restaurants WHERE restaurant_id = '30075445'

Die obige Abfrage gibt die folgenden Ergebnisse zurück:

Vertikale Abflachung

Es ist möglich, ein Array von Dokumenten abzurufen, als wäre es eine separate Tabelle. Nehmen Sie zum Beispiel die folgende JSON-Struktur aus der Restaurantsammlung:

{
  "_id" : ObjectId("568c37b748ddf53c5ed98932"),
  "address" : {
    "building" : "1007",
    "coord" : [-73.856077, 40.848447],
    "street" : "Morris Park Ave",
    "zipcode" : "10462"
  },
  "borough" : "Bronx",
  "cuisine" : "Bakery",
  "grades" : [{
      "date" : ISODate("2014-03-03T00:00:00Z"),
      "grade" : "A",
      "score" : 2
    }, {
      "date" : ISODate("2013-09-11T00:00:00Z"),
      "grade" : "A",
      "score" : 6
    }, {
      "date" : ISODate("2013-01-24T00:00:00Z"),
      "grade" : "A",
      "score" : 10
    }, {
      "date" : ISODate("2011-11-23T00:00:00Z"),
      "grade" : "A",
      "score" : 9
    }, {
      "date" : ISODate("2011-03-10T00:00:00Z"),
      "grade" : "B",
      "score" : 14
    }],
  "name" : "Morris Park Bake Shop",
  "restaurant_id" : "30075445"
}

Durch vertikales Abflachen können Sie das Noten-Array als separate Tabelle abrufen:

SELECT * FROM [restaurants.grades]

Diese Abfrage gibt den folgenden Datensatz zurück:

Möglicherweise möchten Sie auch Informationen aus der Basistabelle „Restaurants“ einschließen. Dies können Sie mit einem Join tun. Abgeflachte Arrays können nur mit dem Stammdokument verbunden werden. Der Connector erwartet, dass der linke Teil des Joins das Array-Dokument ist, das Sie vertikal abflachen möchten. Deaktivieren Sie SupportEnhancedSQL zum Verknüpfen verschachtelter Azure Cosmos DB Dokumente - dieser Abfrage wird durch die Azure Cosmos DB API unterstützt.

SELECT [restaurants].[restaurant_id], [restaurants.grades].* FROM`[Restaurants.Noten] `JOIN` [Restaurants] `WHERE [restaurants].name = 'Morris Park Bake Shop'

Diese Abfrage gibt den folgenden Datensatz zurück:

JSON-Funktionen

Der Connector kann JSON-Strukturen als Spaltenwerte zurückgeben. Der Connector ermöglicht Ihnen die Verwendung von Standard-SQL-Funktionen zum Arbeiten mit diesen JSON-Strukturen. Die Beispiele in diesem Abschnitt verwenden das folgende Array:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

JSON_EXTRACT

Die Funktion JSON_EXTRACT kann einzelne Werte aus einem JSON-Objekt extrahieren. Die folgende Abfrage gibt die unten gezeigten Werte basierend auf dem JSON-Pfad zurück, der als zweites Argument an die Funktion übergeben wird:

SELECT Name, JSON_EXTRACT(grades,'[0].grade') AS Grade, JSON_EXTRACT(grades,'[0].score') AS Score FROM Students;

JSON_ANZAHL

Die Funktion JSON_COUNT gibt die Anzahl der Elemente in einem JSON-Array innerhalb eines JSON-Objekts zurück. Die folgende Abfrage gibt die Anzahl der Elemente zurück, die durch den JSON-Pfad angegeben werden, der als zweites Argument an die Funktion übergeben wird:

SELECT Name, JSON_COUNT(grades,'[x]') AS NumberOfGrades FROM Students;

JSON_SUM

Die Funktion JSON_SUM gibt die Summe der numerischen Werte eines JSON-Arrays innerhalb eines JSON-Objekts zurück. Die folgende Abfrage gibt die Summe der Werte zurück, die durch den JSON-Pfad angegeben werden, der als zweites Argument an die Funktion übergeben wird:

SELECT Name, JSON_SUM(score,'[x].score') AS TotalScore FROM Students;

JSON_MIN

Die Funktion JSON_MIN gibt den niedrigsten numerischen Wert eines JSON-Arrays innerhalb eines JSON-Objekts zurück. Die folgende Abfrage gibt den Mindestwert zurück, der durch den JSON-Pfad angegeben wird, der als zweites Argument an die Funktion übergeben wird:

SELECT Name, JSON_MIN(score,'[x].score') AS LowestScore FROM Students;

JSON_MAX

Die Funktion JSON_MAX gibt den höchsten numerischen Wert eines JSON-Arrays innerhalb eines JSON-Objekts zurück. Die folgende Abfrage gibt den Maximalwert zurück, der durch den JSON-Pfad angegeben wird, der als zweites Argument an die Funktion übergeben wird:

SELECT Name, JSON_MAX(score,'[x].score') AS HighestScore FROM Students;

DOKUMENTIEREN

Mit der Funktion DOCUMENT kann das gesamte Dokument als JSON-Zeichenfolge abgerufen werden. Sehen Sie sich als Beispiel die folgende Abfrage und ihr Ergebnis an:

SELECT DOCUMENT(*) FROM Customers;

Die obige Abfrage gibt das gesamte Dokument wie gezeigt zurück.

{ "id": 12, "name": "Lohia Manufacturers Inc.", "address": { "street": "Main Street", "city": "Chapel Hill", "state": "NC"}, "offices":`[ "Chapel Hill", "London", "New York" ], `"annual_revenue": 35,600,000 }

Integrierte SQL- API Funktionen

Cosmos DB unterstützt auch eine Reihe integrierter Funktionen für allgemeine Vorgänge, die in Abfragen verwendet werden können. Hier sind einige Beispiele, wie sie als Teil von Select-Spalten oder der WHERE-Klausel verwendet werden können:

Verwenden integrierter Funktionen als Teil von SELECT-Spalten

SELECT IS_NUMBER(user_id) AS ISN_ATTR, IS_NUMBER(id) AS ISN_ID FROM [users]
SELECT POWER(user_id, 2) AS POWERSSS, LENGTH(id) AS LENGTH_ID, PI() AS JustThePI FROM [users]

Verwenden Sie integrierte Funktionen als Teil der WHERE-Klausel

SELECT * FROM`[Benutzer] `WHERE STARTSWITH(middle_name, 'G')
SELECT * FROM`[Benutzer] `WHERE REPLACE(middle_name, 'Chr', '___') = '___istopher'

Mathematische Funktionen

Die mathematischen Funktionen führen jeweils eine Berechnung auf der Grundlage der als Argumente bereitgestellten Eingabewerte durch und geben einen numerischen Wert zurück. Hier ist eine Tabelle der unterstützten integrierten mathematischen Funktionen.

Typprüfungsfunktionen

Mit den Typprüfungsfunktionen können Sie den Typ eines Ausdrucks in SQL-Abfragen prüfen. Mithilfe von Typprüfungsfunktionen lässt sich der Typ von Eigenschaften in Dokumenten dynamisch bestimmen, wenn er variabel oder unbekannt ist. Hier ist eine Tabelle der unterstützten integrierten Typprüfungsfunktionen.

Stre-Funktionen

Die folgenden Skalarfunktionen führen eine Operation an einem Zeichenfolgen-Eingabewert aus und geben einen Zeichenfolgen-, numerischen oder Booleschen Wert zurück. Hier ist eine Tabelle der integrierten Zeichenfolgenfunktionen:

Array-Funktionen

Die folgenden Skalarfunktionen führen eine Operation an einem Array-Eingabewert aus und geben einen numerischen, booleschen oder Array-Wert zurück. Hier ist eine Tabelle der integrierten Array-Funktionen:

Verschachtelte Funktionen

Sie können auch verschachtelte integrierte Funktionen ausführen, die ebenfalls serverseitig verarbeitet werden:

i.e. SELECT TOP 10 CONCAT(SUBSTRING(UPPER(cuisine), 0, 3), '-cuisine') FROM [restaurants]

SQL- API GRUPPE NACH

Die GROUP BY-Klausel unterteilt die Ergebnisse der Abfrage nach den Werten einer oder mehrerer angegebener Eigenschaften. Dieser Operation wird aufgrund einiger API Einschränkungen teilweise serverseitig ausgeführt. Wir müssen dennoch eine clientseitige Gruppierung durchführen.

GROUP BY Beispiele

SELECT COUNT(*) AS CNT, gender FROM`[Benutzer] `GROUP BY gender

SELECT COUNT(*) AS CNT, gender, doc_type FROM`[Benutzer] `GROUP BY gender, doc_type

Abfragezuordnung (SQL- API)

Der Connector ordnet SQL-Abfragen den entsprechenden Azure Cosmos DB SQL API Abfragen zu. Eine detaillierte Beschreibung aller Transformations liegt außerhalb des Rahmens, wir werden jedoch einige der verwendeten allgemeinen Elemente beschreiben. Der Connector nutzt SQL- API Funktionen wie das Aggregationsframework, um die gewünschten Ergebnisse zu berechnen.

SELECT-Abfragen

Da alle Anfragen an eine bestimmte Sammlung gesendet werden können, können wir jede konstante Zeichenfolge als Tabellennamen an die API senden. Gemäß dem Azure Portal-Standard verwenden wir das Zeichen „C“ als Tabellennamen.

WÄHLEN Sie ID, Name AUS Benutzern

WÄHLEN Sie C.id, C.name AUS C

SELECT * FROM Benutzer WHERE name = 'A'

SELECT * FROM C WHERE C.name = 'A'

SELECT * FROM Benutzer WHERE Name = 'A' ODER Email = 'zoe55@gmail.com'

SELECT * FROM C WHERE C.Name = 'A' ODER C. Email = 'zoe55@gmail.com'

SELECT id, grantamt FROM WeltBank WHERE grantamt IN (4500000, 85400000) OR grantamt = 16200000

SELECT C.id, C.grantamt FROM C WHERE C.grantamt IN (4500000, 85400000) OR C.grantamt = 16200000

SELECT * FROM WeltBank WHERE CountryCode = 'A' ORDER BY TotalCommAmt ASC

SELECT * FROM C WHERE C.countrycode = 'AL' ORDER BY C.totalcommamt ASC

SELECT * FROM WeltBank WHERE CountryCode = 'A' ORDER BY TotalCommAmt DESC

SELECT * FROM C WHERE C.countrycode = 'AL' ORDER BY C.totalcommamt DESC

Aggregierte Abfragen

Der Connector nutzt dies in großem Umfang für verschiedene aggregierte Abfragen. Nachfolgend einige Beispiele:

SELECT COUNT(grantamt) AS COUNT_GRAMT FROM Weltbank

SELECT COUNT(C.grantamt) AS COUNT_GRAMT FROM C

SELECT SUM(grantamt) AS SUM_GRAMT FROM Weltbank

SELECT SUM(C.grantamt) AS SUM_GRAMT FROM C

Integrierte Funktionen

SELECT IS_NUMBER(grantamt) AS ISN_ATTR, IS_NUMBER(id) AS ISN_ID FROM Weltbank

SELECT IS_NUMBER(C.grantamt) AS ISN_ATTR, IS_NUMBER(C.id) AS ISN_ID FROM C

SELECT POWER(totalamt, 2) AS POWERS_A, LENGTH(id) AS LENGTH_ID, PI() AS ThePI FROM WorldBank

SELECT POWER(C.totalamt, 2) AS POWERS_A, LENGTH(C.id) AS LENGTH_ID, PI() AS ThePI FROM C

Benutzerdefinierte Schemadefinitionen

Sie können die mit Automatische Schemaerkennung erstellten Tabellenschemata erweitern, indem Sie sie in Schema speichern. Die Schema haben ein einfaches Format, das die Bearbeitung der Schemata erleichtert.

Generieren von Schemadateien

Satz GenerateSchemaFiles auf „OnStart“, um Schemata für alle Tabellen beizubehalten, wenn Sie eine Verbindung herstellen. Sie können auch nach Bedarf Tabellenschemata generieren: Set GenerateSchemaFiles auf „OnUse“ und führen Sie eine SELECT Abfrage an die Tabelle aus.

Betrachten Sie beispielsweise ein Schema für den Datensatz „Restaurants“. Dies ist ein Beispieldatensatz, der von Azure Cosmos DB bereitgestellt wird.

Nachfolgend sehen Sie ein Beispieldokument aus der Sammlung:

{
  "address":{
    "building":"461",
      "coord":[
        -74.138492,
        40.631136
      ],
      "street":"Port Richmond Ave",
      "zipcode":"10302"
   },
   "borough":"Staten Island",
   "cuisine":"Other",
   "name":"Indian Oven",
   "restaurant_id":"50018994"
}

Anpassen eines Schemas

Wann GenerateSchemaFiles gesetzt ist, speichert der Connector Schemata in dem durch angegebenen Ordner Location-Eigenschaft. Sie können dann das Spaltenverhalten im resultierenden Schema ändern.

Das folgende Schema verwendet die other:bsonpath Eigenschaft, um zu definieren, wo in der Sammlung die Daten für eine bestimmte Spalte abgerufen werden sollen. Mit diesem Modell können Sie beliebige Hierarchieebenen abflachen.

Unten finden Sie die entsprechenden Spaltendefinitionen für den Datensatz „Restaurants“. In Beispiel für benutzerdefiniertes Schema, finden Sie das vollständige Schema.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">

  <rsb:info title="StaticRestaurants" description="Custom Schema for the restaurants data set.">
    <!-- Column definitions -->
    <attr   name="_rid"               xs:type="string"   key="true"   other:collrid="hWdRAKRi3Pg=" other:dbrid="hWdRAA==" other:partitionpath="/name" />
    <attr   name="borough"            xs:type="string"   />
    <attr   name="cuisine"            xs:type="string"   />
    <attr   name="address.building"   xs:type="string"   />
    <attr   name="address.street"     xs:type="string"   />
    <attr   name="address.coord.0"    xs:type="double"   />
    <attr   name="address.coord.1"    xs:type="double"   />
    <input name="rows@next" desc="Internal attribute used for paging through data."  />
  </rsb:info>

  <rsb:set attr="collection" value="restaurants"/>

</rsb:script>

Beispiel für ein benutzerdefiniertes Schema

Dieser Abschnitt enthält ein vollständiges Schema info Abschnitt ermöglicht eine relationale Ansicht eines Azure Cosmos DB Objekts. Weitere Einzelheiten finden Sie unter Benutzerdefinierte Schemadefinitionen. Die folgende Tabelle ermöglicht die Befehle SELECT, INSERT, UPDATE und DELETE, wie sie in den Abschnitten GET, POST, MERGE und DELETE des folgenden Schema implementiert sind.

Kopieren Sie die rows@next Eingabe wie sie ist in Ihr Schema. Die Operationen, wie cosmosdbadoSysData, sind interne Implementierungen und können auch so kopiert werden.

Setzen Sie das Location-Eigenschaft für das Dateiverzeichnis, das die Schema enthalten wird.

Beim Erstellen benutzerdefinierter Schemata wird das Attribut für _rid, unten gezeigt, ist erforderlich.

Außerdem sind drei Eigenschaften für die _rid-Spaltendefinition erforderlich:

• other:dbrid befindet sich in der _self-Eigenschaft eines Elements in der Sammlung, nach „dbs/“.
• other:collrid befindet sich in der _self-Eigenschaft eines Elements in der Sammlung, nach „/colls/“.
• other:partitionpath bezieht sich auf den Namen der Partition, die beim Erstellen der Sammlung angegeben wurde.

<rsb:script xmlns:rsb="http://www.rssbus.com/ns/rsbscript/2">

  <rsb:info title="StaticRestaurants" description="Custom Schema for the restaurants data set.">
    <!-- Column definitions -->
    <attr   name="_rid"               xs:type="string"   key="true"   other:collrid="hWdRAKRi3Pg=" other:dbrid="hWdRAA==" other:partitionpath="/name" />
    <attr   name="borough"            xs:type="string"   />
    <attr   name="cuisine"            xs:type="string"   />
    <attr   name="address.building"   xs:type="string"   />
    <attr   name="address.street"     xs:type="string"   />
    <attr   name="address.coord.0"    xs:type="double"   />
    <attr   name="address.coord.1"    xs:type="double"   />
    <input name="rows@next" desc="Internal attribute used for paging through data."  />
  </rsb:info>

  <rsb:script method="GET">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="POST">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="MERGE">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

  <rsb:script method="DELETE">
    <rsb:call op="cosmosdbadoSysData">
      <rsb:push />
    </rsb:call>
  </rsb:script>

</rsb:script>

Systemtabellen

Sie können die in diesem Abschnitt beschriebenen Systemtabellen Abfrage, um auf Schema, Informationen zur Datenquellenfunktionalität und Statistiken zu Operation Charge.

Schematabellen

Die folgenden Tabellen geben Datenbankmetadaten für Azure Cosmos DB zurück:

• sys_catalogs: Listet die verfügbaren Datenbanken auf.
• sys_schemas: Listet die verfügbaren Schemata auf.
• sys_tables: Listet die verfügbaren Tabellen und Ansichten auf.
• sys_tablecolumns: Beschreibt die Spalten der verfügbaren Tabellen und Ansichten.
• sys_procedures: Beschreibt die verfügbaren gespeicherten Prozeduren.
• sys_procedureparameters: Beschreibt Parameter gespeicherter Prozeduren.
• sys_keycolumns: Beschreibt die Primär- und Fremdschlüssel.
• sys_indexes: Beschreibt die verfügbaren Indizes.

Datenquellentabellen

Die folgenden Tabellen enthalten Informationen dazu, wie eine Verbindung zur Datenquelle hergestellt und diese Abfrage wird:

• sys_connection_props: Gibt Informationen zu den verfügbaren Verbindungseigenschaften zurück.
• sys_sqlinfo: Beschreibt die SELECT-Abfragen, die der Connector an die Datenquelle auslagern kann.

Abfrageinformationstabellen

Die folgende Tabelle gibt Abfrage für Datenänderungsabfragen zurück, einschließlich Charge:

• Systemidentität: Gibt Informationen zu Charge oder einzelnen Updates zurück.

Sys_catalogs

Listet die verfügbaren Datenbanken auf.

Die folgende Abfrage ruft alle durch die Verbindungszeichenfolge ermittelten Datenbanken ab:

SELECT * FROM sys_catalogs

Spalten

Sys_schemas

Listet die verfügbaren Schemas auf.

Die folgende Abfrage ruft alle verfügbaren Schemas ab:

SELECT * FROM sys_schemas

Spalten

Sys_tables

Listet die verfügbaren Tabellen auf.

Die folgende Abfrage ruft die verfügbaren Tabellen und Ansichten ab:

SELECT * FROM sys_tables

Spalten

Sys_tablecolumns

Beschreibt die Spalten der verfügbaren Tabellen und Ansichten.

Die folgende Abfrage gibt die Spalten und Datentypen für die Tabelle [].[Entities].Customers zurück:

SELECT ColumnName, DataTypeName FROM sys_tablecolumns WHERE TableName='Customers' AND CatalogName='' AND SchemaName='Entities'

Spalten

Sys_procedures

Listet die verfügbaren gespeicherten Prozeduren auf.

Die folgende Abfrage ruft die verfügbaren gespeicherten Prozeduren ab:

SELECT * FROM sys_procedures

Spalten

Sys_procedureparameters

Beschreibt Parameter gespeicherter Prozeduren.

Die folgende Abfrage gibt Informationen zu allen Eingabeparametern für die gespeicherte EVAL-Prozedur zurück:

SELECT * FROM sys_procedureparameters WHERE ProcedureName='EVAL' AND Direction=1 OR Direction=2

Spalten

Sys_keycolumns

Beschreibt die Primär- und Fremdschlüssel.

Die folgende Abfrage ruft den Primärschlüssel für die Tabelle [].[Entities].Customers ab:

SELECT * FROM sys_keycolumns WHERE IsKey='True' AND TableName='Customers' AND CatalogName='' AND SchemaName='Entities'

Spalten

Sys_foreignkeys

Beschreibt die Fremdschlüssel.

Die folgende Abfrage ruft alle Fremdschlüssel ab, die auf andere Tabellen verweisen:

SELECT * FROM sys_foreignkeys WHERE ForeignKeyType = 'FOREIGNKEY_TYPE_IMPORT'

Spalten

Sys_primarykeys

Beschreibt die Primärschlüssel.

Die folgende Abfrage ruft die Primärschlüssel aus allen Tabellen und Ansichten ab:

SELECT * FROM sys_primarykeys

Spalten

Sys_indexes

Beschreibt die verfügbaren Indizes. Durch das Filtern nach Indizes können Sie selektivere Abfragen mit schnelleren Abfrage schreiben.

Die folgende Abfrage ruft alle Indizes ab, die keine Primärschlüssel sind:

SELECT * FROM sys_indexes WHERE IsPrimary='false'

Spalten

Sys_connection_props

Gibt Informationen zu den verfügbaren Verbindungseigenschaften und den in der Verbindungszeichenfolge festgelegten Eigenschaften zurück.

Bei der Abfrage dieser Tabelle sollte die Konfigurationsverbindungszeichenfolge verwendet werden:

jdbc:cdata:cosmosdb:config:

Mit dieser Verbindungszeichenfolge können Sie diese Tabelle ohne eine gültige Verbindung Abfrage.

Die folgende Abfrage ruft alle Verbindungseigenschaften ab, die in der Verbindungszeichenfolge festgelegt oder über einen Standardwert gesetzt wurden:

SELECT * FROM sys_connection_props WHERE Value <> ''

Spalten

Sys_sqlinfo

Beschreibt die SELECT- Abfrage, die der Connector an die Datenquelle auslagern kann.

Entdecken Sie die SELECT-Funktionen der Datenquelle

Nachfolgend sehen Sie einen Beispieldatensatz mit SQL-Funktionen. Einige Aspekte der SELECT-Funktionalität werden in einer durch Kommas getrennten Liste zurückgegeben, sofern sie unterstützt werden. Andernfalls enthält die Spalte NO.

Die folgende Abfrage ruft die Operatoren ab, die in der WHERE-Klausel verwendet werden können:

SELECT * FROM sys_sqlinfo WHERE Name = 'SUPPORTED_OPERATORS'

Beachten Sie, dass einzelne Tabellen unterschiedliche Einschränkungen oder Anforderungen an die WHERE-Klausel haben können; siehe NoSQL-Datenbank Abschnitt für weitere Informationen.

Spalten

Systemidentität

Gibt Informationen zu versuchten Änderungen zurück.

Die folgende Abfrage ruft die IDs der geänderten Zeilen in einer Operation Charge:

SELECT * FROM sys_identity

Spalten

Systeminformationen

Beschreibt die verfügbaren Systeminformationen.

Die folgende Abfrage ruft alle Spalten ab:

SELECT * FROM sys_information

Spalten

Gespeicherte Prozeduren

Gespeicherte Prozeduren sind funktionsähnliche Schnittstellen, die die Funktionalität des Connectors über einfache SELECT/INSERT/UPDATE/DELETE-Vorgänge mit Azure Cosmos DB hinaus erweitern.

Gespeicherte Prozeduren akzeptieren eine Liste von Parametern, führen ihre beabsichtigte Funktion aus und geben dann alle relevanten Antwortdaten von Azure Cosmos DB zurück, zusammen mit einem Hinweis darauf, ob die Prozedur erfolgreich war oder fehlgeschlagen ist.

Gespeicherte Prozeduren für den Azure Cosmos DB Connector

Dokument hinzufügen

Fügen Sie die gesamte JSON-Zeichenfolge in CosmosDB ein.

Eingang

Ergebnissatzspalten

Schema erstellen

Erstellt eine Schema für die Sammlung.

Schema erstellen

Erstellt eine lokale Schema (.rsd) aus einer vorhandenen Tabelle oder Ansicht im Datenmodell.

Die Schema wird in dem Verzeichnis erstellt, das in festgelegt ist Location Verbindungseigenschaft, wenn dieses Verfahren ausgeführt wird. Sie können die Datei bearbeiten, um Spalten ein- oder auszuschließen, Spalten umzubenennen oder Spaltendatentypen anzupassen.

Der Connector überprüft die Location um zu bestimmen, ob die Namen von .rsd-Dateien mit einer Tabelle oder Ansicht im Datenmodell übereinstimmen. Wenn ein Duplikat vorhanden ist, hat die Schema Vorrang vor der Standardinstanz dieser Tabelle im Datenmodell. Wenn eine Schema in vorhanden ist Location das nicht mit einer vorhandenen Tabelle oder Ansicht übereinstimmt, wird dem Datenmodell des Connectors ein neuer Tabellen- oder Ansichtseintrag hinzugefügt.

Eingang

Ergebnissatzspalten

GetOAuthAccessToken

Ruft das OAuth-Zugriffstoken von CosmosDB ab.

Eingang

Ergebnissatzspalten

GetOAuthAuthorizationURL

Ruft die CosmosDB-Autorisierungs URL ab. Greifen Sie in einem Webbrowser auf die in der Ausgabe zurückgegebene URL zu. Dadurch wird das Zugriffstoken angefordert, das als Teil der Verbindungszeichenfolge zu CosmosDB verwendet werden kann.

Eingang

Ergebnissatzspalten

Aktualisieren Sie das OAuthAccessToken

Aktualisiert das OAuth-Zugriffstoken, das für die Authentifizierung bei CosmosDB verwendet wird.

Eingang

Ergebnissatzspalten

Erweiterte Konfigurationseigenschaften

Die erweiterten Konfigurationseigenschaften sind die verschiedenen Optionen, die zum Herstellen einer Verbindung verwendet werden können. Dieser Abschnitt enthält eine vollständige Liste der Optionen, die Sie konfigurieren können. Klicken Sie auf die Links, um weitere Einzelheiten zu erfahren.

Authentifizierung

Azure-Authentifizierung

OAuth

JWT OAuth

SSL

Schema

Verschiedenes

Authentifizierung

Dieser Abschnitt enthält eine vollständige Liste der Authentifizierungseigenschaften, die Sie konfigurieren können.

AuthScheme

Der beim Herstellen einer Verbindung mit Azure Cosmos DB zu verwendende Authentifizierungstyp.

Mögliche Werte

AccountKey, AzureAD, AzureServicePrincipal, AzureServicePrincipalCert

Datentyp

string

Standardwert

AccountKey

Hinweise

• AccountKey: Legen Sie dies fest, um die Authentifizierung mit AccountKey durchzuführen und AccountEndpoint.
• Microsoft Entra ID: Legen Sie dies fest, um die Microsoft Entra ID OAuth-Authentifizierung durchzuführen.
• AzureServicePrincipal: Legen Sie dies fest, um die Authentifizierung als Microsoft Entra-Dienstprinzipal unter Verwendung eines Clientgeheimnisses durchzuführen.
• AzureServicePrincipalCert: Legen Sie dies fest, um sich mithilfe eines Zertifikats als Microsoft Entra-Dienstprinzipal zu authentifizieren.

Kontoendpunkt

Der Wert sollte die Cosmos DB-Konto-URL aus dem Schlüssel-Blade des Cosmos DB-Kontos sein.

Datentyp

string

Standardwert

""

Hinweise

Der Wert sollte die Cosmos DB-Konto-URL aus dem Schlüssel-Blade des Cosmos DB-Kontos sein.

Kontoschlüssel

Ein Hauptschlüsseltoken oder ein Ressourcentoken zum Herstellen einer Verbindung mit der Azure Cosmos DB REST- API.

Datentyp

string

Standardwert

""

Hinweise

Navigieren Sie im Azure Portal zum Cosmos DB-Dienst und wählen Sie Ihr Azure Cosmos DB Konto aus. Wechseln Sie im Ressourcenmenü zur Seite „Schlüssel“. Suchen Sie den PRIMARY KEY-Wert und legen Sie Token auf diesen Wert fest.

Token-Typ

Bezeichnet den Tokentyp: Master oder Ressource.

Mögliche Werte

master, resource

Datentyp

string

Standardwert

master

Hinweise

Der Hauptschlüssel wird bei der Erstellung eines Kontos erstellt. Es gibt zwei Sätze von Hauptschlüsseln, den Primärschlüssel und den Sekundärschlüssel. Der Administrator des Kontos kann dann mithilfe des Sekundärschlüssels eine Schlüsselrotation durchführen. Darüber hinaus kann der Kontoadministrator die Schlüssel bei Bedarf auch neu generieren.

Ressourcentoken werden erstellt, wenn Benutzern in einer Datenbank Zugriffsberechtigungen für eine präzise Zugriffskontrolle auf eine Ressource, auch Berechtigungsressource genannt, zugewiesen werden. Eine Berechtigungsressource enthält ein Hash-Ressourcentoken, das mit den Informationen zum Ressourcenpfad und Zugriffstyp erstellt wird, auf den ein Benutzer Zugriff hat. Das Berechtigungsressourcentoken ist zeitlich begrenzt und die Gültigkeitsdauer kann überschrieben werden. Wenn auf eine Berechtigungsressource reagiert wird (POST, GET, PUT), wird ein neues Ressourcentoken generiert.

Azure Authentifizierung

Dieser Abschnitt enthält eine vollständige Liste der Azure-Authentifizierungseigenschaften, die Sie konfigurieren können.

AzureTenant

Der Microsoft Online-Mandant, der für den Datenzugriff verwendet wird. Wenn nicht angegeben, wird Ihr Standardmandant verwendet.

Datentyp

string

Standardwert

""

Hinweise

Der Microsoft Online-Mandant, der für den Datenzugriff verwendet wird. Beispiel: contoso.onmicrosoft.com. Alternativ können Sie die Mandanten-ID angeben. Dieser Wert ist die Verzeichnis-ID im Azure-Portal > Microsoft Entra ID > Eigenschaften.

Normalerweise ist es nicht notwendig, den Mandanten anzugeben. Dies kann von Microsoft automatisch ermittelt werden, wenn der OAuthGrantType verwendet wird auf CODE (Standard) eingestellt. Es kann jedoch fehlschlagen, wenn der Benutzer mehreren Mandanten angehört. Zum Beispiel, wenn ein Administrator von Domäne A einen Benutzer von Domäne B als Gastbenutzer einlädt. Der Benutzer gehört nun beiden Mandanten an. Es ist eine gute Praxis, den Mandanten anzugeben, obwohl es im Allgemeinen funktionieren sollte, ohne ihn angeben zu müssen.

AzureTenant ist beim Festlegen von OAuthGrantType erforderlich zu CLIENT. Bei der Verwendung von Client-Anmeldeinformationen gibt es keinen Benutzerkontext. Die Anmeldeinformationen werden aus dem Kontext der App selbst übernommen. Microsoft erlaubt zwar weiterhin den Abruf von Client-Anmeldeinformationen ohne Angabe des Mandanten, aber die Wahrscheinlichkeit, den spezifischen Mandanten auszuwählen, mit dem Sie arbeiten möchten, ist viel geringer. Aus diesem Grund benötigen wir AzureTenant muss bei allen Client-Anmeldeinformationen-Verbindungen ausdrücklich angegeben werden, um sicherzustellen, dass Sie Anmeldeinformationen erhalten, die für die Domäne gelten, mit der Sie eine Verbindung herstellen möchten.

Der Microsoft Online-Mandant, der für den Datenzugriff verwendet wird. Beispiel: contoso.onmicrosoft.com. Alternativ können Sie die Mandanten-ID angeben. Dieser Wert ist die Verzeichnis-ID im Azure-Portal > Microsoft Entra ID > Eigenschaften.

Normalerweise ist es nicht notwendig, den Mandanten anzugeben. Dies kann von Microsoft automatisch ermittelt werden, wenn der OAuthGrantType verwendet wird auf CODE (Standard) eingestellt. Es kann jedoch fehlschlagen, wenn der Benutzer mehreren Mandanten angehört. Zum Beispiel, wenn ein Administrator von Domäne A einen Benutzer von Domäne B als Gastbenutzer einlädt. Der Benutzer gehört nun beiden Mandanten an. Es ist eine gute Praxis, den Mandanten anzugeben, obwohl es im Allgemeinen funktionieren sollte, ohne ihn angeben zu müssen.

AzureTenant ist beim Festlegen von OAuthGrantType erforderlich zu CLIENT. Bei der Verwendung von Client-Anmeldeinformationen gibt es keinen Benutzerkontext. Die Anmeldeinformationen werden aus dem Kontext der App selbst übernommen. Microsoft erlaubt zwar weiterhin den Abruf von Client-Anmeldeinformationen ohne Angabe des Mandanten, aber die Wahrscheinlichkeit, den spezifischen Mandanten auszuwählen, mit dem Sie arbeiten möchten, ist viel geringer. Aus diesem Grund benötigen wir AzureTenant muss bei allen Client-Anmeldeinformationen-Verbindungen explizit angegeben werden, um sicherzustellen, dass Sie Anmeldeinformationen erhalten, die für die Domäne gelten, mit der Sie eine Verbindung herstellen möchten.

Azure-Umgebung

Die beim Herstellen einer Verbindung zu verwendende Azure-Umgebung.

Mögliche Werte

GLOBAL, CHINA, USGOVT, USGOVTDOD

Datentyp

string

Standardwert

GLOBAL

Hinweise

In den meisten Fällen funktioniert es, die Umfeld auf global eingestellt zu lassen. Wenn Ihr Azure-Konto jedoch einer anderen Umfeld hinzugefügt wurde, wird die AzureEnvironment kann verwendet werden, um die Umfeld anzugeben. Die verfügbaren Werte sind GLOBAL, CHINA, USGOVT, USGOVTDOD.

OAuth

Dieser Abschnitt enthält eine vollständige Liste der OAuth-Eigenschaften, die Sie konfigurieren können.

OAuth initiieren

Legen Sie diese Eigenschaft fest, um den Prozess zum Abrufen oder Aktualisieren des OAuth-Zugriffstokens beim Herstellen einer Verbindung zu starten.

Mögliche Werte

OFF, GETANDREFRESH, REFRESH

Datentyp

string

Standardwert

OFF

Hinweise

Folgende Optionen stehen zur Verfügung:

1. OFF: Gibt an, dass der OAuth-Flow vollständig vom Benutzer gehandhabt wird. Zur Authentifizierung ist ein OAuthAccessToken erforderlich.
2. GETANDREFRESH: Gibt an, dass der gesamte OAuth-Flow vom Connector verarbeitet wird. Wenn derzeit kein Token vorhanden ist, wird es durch eine entsprechende Aufforderung an den Benutzer über den Browser abgerufen. Wenn ein Token vorhanden ist, wird es bei Bedarf aktualisiert.
3. REFRESH: Gibt an, dass der Connector nur das Aktualisieren des OAuthAccessToken übernimmt. Der Benutzer wird vom Connector nie aufgefordert, sich über den Browser zu authentifizieren. Der Benutzer muss zunächst das Abrufen des OAuthAccessToken und des OAuthRefreshToken übernehmen.

OAuthClientId

Die Client-ID, die zugewiesen wird, wenn Sie Ihre Anwendung bei einem OAuth-Autorisierungsserver registrieren.

Datentyp

string

Standardwert

""

Hinweise

Im Rahmen der Registrierung einer OAuth-Anwendung erhalten Sie die OAuthClientId-Wert, manchmal auch Consumer-Schlüssel genannt, und ein Client-Geheimnis, das OAuthClientSecret.

OAuthClientSecret

Das Client-Geheimnis, das zugewiesen wird, wenn Sie Ihre Anwendung bei einem OAuth-Autorisierungsserver registrieren.

Datentyp

string

Standardwert

""

Hinweise

Im Rahmen der Registrierung einer OAuth-Anwendung erhalten Sie die OAuthClientId, auch Consumer-Schlüssel genannt. Sie erhalten außerdem ein Client-Geheimnis, auch Consumer-Geheimnis genannt. Legen Sie das Client-Geheimnis im OAuthClientSecret Eigentum.

OAuth-Zugriffstoken

Der Zugriffstoken für die Verbindung per OAuth.

Datentyp

string

Standardwert

""

Hinweise

Der OAuthAccessToken Eigenschaft wird für die Verbindung über OAuth verwendet. Die OAuthAccessToken wird im Rahmen des Authentifizierungsprozesses vom OAuth-Server abgerufen. Es hat ein serverabhängiges Timeout und kann zwischen Anfragen wiederverwendet werden.

Das Zugriffstoken wird anstelle Ihres Benutzernamens und Passworts verwendet. Das Zugriffstoken schützt Ihre Anmeldeinformationen, indem es sie auf dem Server speichert.

OAuthSettingsLocation

Der Speicherort der Einstellungsdatei, in der OAuth-Werte gespeichert werden, wenn InitiateOAuth auf GETANDREFRESH oder REFRESH eingestellt ist. Alternativ können Sie diesen Speicherort im Speicher halten, indem Sie einen Wert angeben, der mit beginnt 'memory://'.

Datentyp

string

Standardwert

%APPDATA%\CosmosDB Data Provider\OAuthSettings.txt

Hinweise

Wenn InitiateOAuth ist auf gesetzt GETANDREFRESH oder REFRESH, der Connector speichert OAuth-Werte, damit der Benutzer die OAuth-Verbindungseigenschaften nicht manuell eingeben muss und die Anmeldeinformationen über Verbindungen oder Prozesse hinweg gemeinsam genutzt werden können.

Anstatt einen Dateipfad anzugeben, können Sie den Speicher verwenden. Speicherorte werden durch einen Wert angegeben, der mit beginnt 'memory://' gefolgt von einer eindeutigen Kennung für diesen Satz von Anmeldeinformationen (z. B. memory://user1). Die Kennung können Sie frei wählen, sie sollte jedoch für den Benutzer eindeutig sein. Im Gegensatz zur dateibasierten Speicherung, bei der die Anmeldeinformationen über Verbindungen hinweg bestehen bleiben, werden die Anmeldeinformationen bei der Speicherspeicherung in den statischen Speicher geladen und die Anmeldeinformationen werden für die Dauer des Prozesses unter Verwendung derselben Kennung zwischen Verbindungen geteilt. Um Anmeldeinformationen außerhalb des aktuellen Prozesses beizubehalten, müssen Sie die Anmeldeinformationen vor dem Schließen der Verbindung manuell speichern. Auf diese Weise können Sie sie in der Verbindung festlegen, wenn der Prozess erneut gestartet wird. Sie können OAuth-Eigenschaftswerte mit einer Abfrage an abrufen sys_connection_props Systemtabelle. Wenn mehrere Verbindungen mit denselben Anmeldeinformationen bestehen, werden die Eigenschaften aus der zuvor geschlossenen Verbindung gelesen.

Der Standardspeicherort ist „%APPDATA%\CosmosDB Data Provider\OAuthSettings.txt“ mit %APPDATA% auf das Konfigurationsverzeichnis des Benutzers gesetzt. Die Standardwerte sind

• Windows: "register://%DSN"
• Unix: "%AppData%..."
• Mac: "%AppData%..."

wobei DSN der Name des aktuellen DSN ist, der in der offenen Verbindung verwendet wird.

Die folgende Tabelle listet den Wert von auf %APPDATA% nach Operationssystem:

Rückruf-URL

Die OAuth-Rückruf URL, zu der bei der Authentifizierung zurückgekehrt werden soll. Dieser Wert muss mit der Rückruf-URL übereinstimmen, die Sie in Ihren App-Einstellungen angeben.

Datentyp

string

Standardwert

""

Hinweise

Während des Authentifizierungsprozesses leitet der OAuth-Autorisierungsserver den Benutzer an diese URL weiter. Dieser Wert muss mit der Rückruf URL übereinstimmen, die Sie in Ihren App-Einstellungen angeben.

OAuthGrantType

Der Berechtigungstyp für den OAuth-Flow.

Mögliche Werte

CODE, CLIENT, PASSWORD

Datentyp

string

Standardwert

CLIENT

Hinweise

Folgende Optionen stehen zur Verfügung: CODE,CLIENT,PASSWORT

OAuthVerifier

Der von der OAuth-Autorisierungs URL zurückgegebene Prüfcode.

Datentyp

string

Standardwert

""

Hinweise

Der von der OAuth-Autorisierungs URL zurückgegebene Prüfcode. Dieser kann auf Systemen verwendet werden, auf denen kein Browser gestartet werden kann, z. B. auf Headless-Systemen.

Authentifizierung auf Headless-Maschinen

Siehe, um die zu erhalten OAuthVerifier Wert.

OAuthSettingsLocation festlegen zusammen mit OAuthVerifier. Beim Verbinden tauscht der Connector die OAuthVerifier für die OAuth-Authentifizierungstoken und speichert sie verschlüsselt am angegebenen Speicherort. Setzen Sie InitiateOAuth zu GETANDREFRESH, um den Austausch zu automatisieren.

Sobald die OAuth-Einstellungsdatei generiert wurde, können Sie entfernen OAuthVerifier aus den Verbindungseigenschaften und verbinden Sie sich mit OAuthSettingsLocation festgelegt.

Um die OAuth-Tokenwerte automatisch zu aktualisieren, legen Sie OAuthSettingsLocation fest und setzen Sie zusätzlich InitiateOAuth zum AKTUALISIEREN.

OAuthRefreshToken

Das OAuth-Aktualisierungstoken für das entsprechende OAuth-Zugriffstoken.

Datentyp

string

Standardwert

""

Hinweise

Der OAuthRefreshToken Eigenschaft wird verwendet, um den OAuthAccessToken zu aktualisieren bei Verwendung der OAuth-Authentifizierung.

OAuthLäuftAbIn

Die Lebensdauer des OAuth AccessToken in Sekunden.

Datentyp

string

Standardwert

""

Hinweise

Mit OAuthTokenTimestamp kombinieren, um zu bestimmen, wann der AccessToken abläuft.

OAuthTokenTimestamp

Der Unix-Epochenzeitstempel in Millisekunden, als das aktuelle Zugriffstoken erstellt wurde.

Datentyp

string

Standardwert

""

Hinweise

Kombinieren Sie es mit OAuthExpiresIn, um zu bestimmen, wann das AccessToken abläuft.

JWT OAuth

Dieser Abschnitt enthält eine vollständige Liste der JWT OAuth-Eigenschaften, die Sie konfigurieren können.

OAuthJWTCert

Der JWT-Zertifikatspeicher.

Datentyp

string

Standardwert

""

Hinweise

Der Name des Zertifikatspeichers für das Client-Zertifikat.

Der OAuthJWTCertType Feld gibt den Typ des durch angegebenen Zertifikatspeichers an OAuthJWTCert. Wenn der Store kennwortgeschützt ist, geben Sie das Kennwort in OAuthJWTCertPassword an.

OAuthJWTCert wird in Verbindung mit OAuthJWTCertSubject verwendet

Feld, um Client-Zertifikate anzugeben. Wenn OAuthJWTCert hat einen Wert und OAuthJWTCertSubject gesetzt ist, wird eine Suche nach einem Zertifikat eingeleitet. Bitte beachten Sie das OAuthJWTCertSubject für weitere Einzelheiten.

Die Bezeichnungen der Zertifikatsspeicher sind plattformabhängig.

Nachfolgend sind die Bezeichnungen der gebräuchlichsten Benutzer- und Maschinen-Zertifikatspeicher in Windows aufgeführt:

In Java ist der Zertifikatsspeicher normalerweise eine Datei, die Zertifikate und optionale private Schlüssel enthält.

Wenn der Zertifikatsspeichertyp PFXFile ist, muss diese Eigenschaft auf den Namen der Datei gesetzt werden. Wenn der Typ PFXBlob ist, muss die Eigenschaft auf den binären Inhalt einer PFX-Datei (d. h. PKCS12-Zertifikatsspeicher) gesetzt werden.

OAuthJWTCertType

Der Typ des Schlüsselspeichers, der das JWT-Zertifikat enthält.

Mögliche Werte

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PUBLIC_KEY_FILE, PUBLIC_KEY_BLOB, SSHPUBLIC_KEY_FILE, SSHPUBLIC_KEY_BLOB, P7BFILE, PPKFILE, XMLFILE, XMLBLOB

Datentyp

string

Standardwert

USER

Hinweise

Diese Eigenschaft kann einen der folgenden Werte annehmen:

OAuthJWTCertPasswort

Das Passwort für das OAuth JWT-Zertifikat.

Datentyp

string

Standardwert

""

Hinweise

Wenn der Zertifikatspeicher von einem Typ ist, der ein Passwort erfordert, wird diese Eigenschaft verwendet, um dieses Passwort anzugeben, damit der Zertifikatspeicher geöffnet werden kann.

OAuthJWTCertSubject

Der Betreff des OAuth JWT-Zertifikats.

Datentyp

string

Standardwert

*

Hinweise

Beim Laden eines Zertifikats wird der Betreff verwendet, um das Zertifikat im Speicher zu lokalisieren.

Wenn keine genaue Übereinstimmung gefunden wird, wird der Speicher nach Betreffs durchsucht, die den Wert der Eigenschaft enthalten.

Wenn immer noch keine Übereinstimmung gefunden wird, wird die Eigenschaft auf eine leere Zeichenfolge gesetzt und kein Zertifikat ausgewählt.

Der spezielle Wert „*“ wählt das erste Zertifikat im Zertifikatspeicher aus.

Der Betreff des Zertifikats ist eine durch Kommas getrennte Liste von Distinguished Name-Feldern und-Werten. Zum Beispiel „CN=www.server.com, OU=test, C=US, E=example@jbexample.com“. Allgemeine Felder und ihre Bedeutungen werden unten angezeigt.

Wenn ein Feldwert ein Komma enthält, muss es in Anführungszeichen gesetzt werden.

SSL

Dieser Abschnitt enthält eine vollständige Liste der SSL-Eigenschaften, die Sie konfigurieren können.

SSLClientCert

Der TLS/SSL-Client-Zertifikatspeicher für die SSL-Client-Authentifizierung (bidirektionales SSL).

Datentyp

string

Standardwert

""

Hinweise

Der Name des Zertifikatspeichers für das Client-Zertifikat.

Der SSLClientCertType Feld gibt den Typ des durch angegebenen Zertifikatspeichers an SSLClientCert. Wenn der Store kennwortgeschützt ist, geben Sie das Kennwort in SSLClientCertPassword an.

SSLClientCert wird in Verbindung mit SSLClientCertSubject verwendet, um Client-Zertifikate anzugeben. Wenn SSLClientCert hat einen Wert und SSLClientCertSubject gesetzt ist, wird eine Suche nach einem Zertifikat eingeleitet. Siehe SSLClientCertSubject für weitere Informationen.

Die Bezeichnungen der Zertifikatsspeicher sind plattformabhängig.

Nachfolgend sind die Bezeichnungen der gebräuchlichsten Benutzer- und Maschinen-Zertifikatspeicher in Windows aufgeführt:

In Java ist der Zertifikatsspeicher normalerweise eine Datei, die Zertifikate und optionale private Schlüssel enthält.

Wenn der Zertifikatsspeichertyp PFXFile ist, muss diese Eigenschaft auf den Namen der Datei gesetzt werden. Wenn der Typ PFXBlob ist, muss die Eigenschaft auf den binären Inhalt einer PFX-Datei gesetzt werden (z. B. PKCS12-Zertifikatsspeicher).

SSLClientCertType

Der Typ des Schlüsselspeichers, der das TLS/SSL-Clientzertifikat enthält.

Mögliche Werte

USER, MACHINE, PFXFILE, PFXBLOB, JKSFILE, JKSBLOB, PEMKEY_FILE, PEMKEY_BLOB, PUBLIC_KEY_FILE, PUBLIC_KEY_BLOB, SSHPUBLIC_KEY_FILE, SSHPUBLIC_KEY_BLOB, P7BFILE, PPKFILE, XMLFILE, XMLBLOB

Datentyp

string

Standardwert

USER

Hinweise

Diese Eigenschaft kann einen der folgenden Werte annehmen:

SSLClientCertPassword

Das Passwort für das TLS/SSL-Client-Zertifikat.

Datentyp

string

Standardwert

""

Hinweise

Wenn der Zertifikatspeicher von einem Typ ist, der ein Passwort erfordert, wird diese Eigenschaft verwendet, um dieses Passwort zum Öffnen des Zertifikatspeichers anzugeben.

SSLClientCertSubject

Der Betreff des TLS/SSL-Client-Zertifikats.

Datentyp

string

Standardwert

*

Hinweise

Beim Laden eines Zertifikats wird der Betreff verwendet, um das Zertifikat im Speicher zu lokalisieren.

Wenn keine genaue Übereinstimmung gefunden wird, wird der Speicher nach Betreffs durchsucht, die den Wert der Eigenschaft enthalten. Wenn immer noch keine Übereinstimmung gefunden wird, wird die Eigenschaft auf eine leere Zeichenfolge gesetzt und kein Zertifikat ausgewählt.

Der spezielle Wert „*“ wählt das erste Zertifikat im Zertifikatspeicher aus.

Der Betreff des Zertifikats ist eine durch Kommas getrennte Liste von Distinguished Name-Feldern und-Werten. Beispiel: „CN=www.server.com, OU=test, C=US, E=support@company.com“. Die allgemeinen Felder und ihre Bedeutungen werden unten angezeigt.

Wenn ein Feldwert ein Komma enthält, muss es in Anführungszeichen gesetzt werden.

SSLServerCert

Das vom Server zu akzeptierende Zertifikat bei einer Verbindung per TLS/SSL.

Datentyp

string

Standardwert

""

Hinweise

Bei Verwendung einer TLS/SSL-Verbindung kann diese Eigenschaft verwendet werden, um das vom Server zu akzeptierende TLS/SSL-Zertifikat anzugeben. Jedes andere Zertifikat, dem der Computer nicht vertraut, wird abgelehnt.

Diese Eigenschaft kann folgende Formen annehmen:

Wenn nicht angegeben, wird jedes vom Computer vertrauenswürdige Zertifikat akzeptiert.

Zertifikate werden vom Computer basierend auf dem Trust Store des Systems als vertrauenswürdig validiert. Der verwendete Trust Store ist der für das System angegebene Wert „javax.net.ssl.trustStore“. Wenn für diese Eigenschaft kein Wert angegeben ist, wird der Standard-Trust Store von Java verwendet (z. B. JAVA_HOME\lib\security\cacerts).

Verwenden Sie „*“, um anzugeben, dass alle Zertifikate akzeptiert werden. Beachten Sie, dass dies aus Sicherheitsgründen nicht empfohlen wird.

Schema

Dieser Abschnitt enthält eine vollständige Liste der Schema, die Sie konfigurieren können.

Standort

Ein Pfad zum Verzeichnis, das die Schema enthält, die Tabellen, Ansichten und gespeicherte Prozeduren definieren.

Datentyp

string

Standardwert

%APPDATA%\CosmosDB Data Provider\Schema

Hinweise

Der Pfad zu einem Verzeichnis, das die Schema für den Connector enthält (.rsd-Dateien für Tabellen und Ansichten, .rsb-Dateien für gespeicherte Prozeduren). Der Ordnerspeicherort kann ein relativer Pfad vom Speicherort der ausführbaren Datei sein. Der Location Eigenschaft wird nur benötigt, wenn Sie Definitionen anpassen möchten (z. B. einen Spaltennamen ändern, eine Spalte ignorieren usw.) oder das Datenmodell mit neuen Tabellen, Ansichten oder gespeicherten Prozeduren erweitern möchten.

Wenn nicht angegeben, ist der Standardspeicherort „%APPDATA%\CosmosDB Data Provider\Schema“ mit %APPDATA% wird auf das Konfigurationsverzeichnis des Benutzers eingestellt:

DurchsuchbareSchemas

Diese Eigenschaft beschränkt die gemeldeten Schemata auf eine Teilmenge der verfügbaren Schemata. Beispiel: BrowsableSchemas=SchemaA,SchemaB,SchemaC.

Datentyp

string

Standardwert

""

Hinweise

Das Auflisten der Schemata aus Datenbanken kann aufwändig sein. Die Bereitstellung einer Liste von Schemata in der Verbindungszeichenfolge verbessert die Leistung.

Tabellen

Diese Eigenschaft beschränkt die gemeldeten Tabellen auf eine Teilmenge der verfügbaren Tabellen. Beispiel: Tabellen=TabelleA,TabelleB,TabelleC.

Datentyp

string

Standardwert

""

Hinweise

Das Auflisten der Tabellen aus einigen Datenbanken kann teuer sein. Die Bereitstellung einer Liste von Tabellen in der Verbindungszeichenfolge verbessert die Leistung des Connectors.

Diese Eigenschaft kann auch als Alternative zum automatischen Auflisten von Ansichten verwendet werden, wenn Sie bereits wissen, mit welchen Sie arbeiten möchten, und es sonst zu viele wären.

Geben Sie die gewünschten Tabellen in einer durch Kommas getrennten Liste an. Jede Tabelle sollte ein gültiger SQL-Bezeichner sein, wobei alle Sonderzeichen mit eckigen Klammern, Anführungszeichen oder Backticks maskiert werden. Beispiel: Tables=TableA,[TableB/WithSlash],WithCatalog.WithSchema.`TableC With Space`.

Beachten Sie, dass Sie beim Herstellen einer Verbindung zu einer Datenquelle mit mehreren Schemata oder Katalogen den vollqualifizierten Namen der Tabelle in dieser Eigenschaft angeben müssen, wie im letzten Beispiel hier, um Mehrdeutigkeiten zwischen Tabellen zu vermeiden, die in mehreren Katalogen oder Schemata vorhanden sind.

Ansichten

Beschränkt die gemeldeten Ansichten auf eine Teilmenge der verfügbaren Tabellen. Beispiel: Ansichten=AnsichtA,AnsichtB,AnsichtC.

Datentyp

string

Standardwert

""

Hinweise

Das Auflisten der Ansichten aus einigen Datenbanken kann teuer sein. Die Bereitstellung einer Liste von Ansichten in der Verbindungszeichenfolge verbessert die Leistung des Connectors.

Diese Eigenschaft kann auch als Alternative zum automatischen Auflisten von Ansichten verwendet werden, wenn Sie bereits wissen, mit welchen Sie arbeiten möchten, und es sonst zu viele wären.

Geben Sie die gewünschten Ansichten in einer durch Kommas getrennten Liste an. Jede Ansicht sollte ein gültiger SQL-Bezeichner sein, wobei alle Sonderzeichen mit eckigen Klammern, Anführungszeichen oder Backticks maskiert werden. Beispiel: Views=ViewA,[ViewB/WithSlash],WithCatalog.WithSchema.`ViewC With Space`.

Beachten Sie, dass Sie beim Herstellen einer Verbindung zu einer Datenquelle mit mehreren Schemata oder Katalogen den vollqualifizierten Namen der Tabelle in dieser Eigenschaft angeben müssen, wie im letzten Beispiel hier, um Mehrdeutigkeiten zwischen Tabellen zu vermeiden, die in mehreren Katalogen oder Schemata vorhanden sind.

Schema

Geben Sie die Azure Cosmos DB Datenbank an, mit der Sie arbeiten möchten.

Datentyp

string

Standardwert

""

Hinweise

Geben Sie die Azure Cosmos DB Datenbank an, mit der Sie arbeiten möchten.

Verschiedenes

Dieser Abschnitt enthält eine vollständige Liste verschiedener Eigenschaften, die Sie konfigurieren können.

Aggregate berechnen

Gibt an, ob der berechnete Wert der Aggregate oder gruppiert nach Partitionsbereich zurückgegeben wird.

Datentyp

bool

Standardwert

true

Hinweise

Gibt an, ob der berechnete Wert der Aggregate oder gruppiert nach Partitionsbereich zurückgegeben wird.

Konsistenzstufe

Bezeichnet den Tokentyp: Master oder Ressource.

Mögliche Werte

STRONG, BOUNDED, SESSION, CONSISTENTPREFIX, EVENTUAL

Datentyp

string

Standardwert

SESSION

Hinweise

Die Konsistenzstufenüberschreibung für Leseoptionen für Dokumente und Anhänge. Die gültigen Werte sind: Stark, Begrenzt, Sitzung oder Eventuell (in der Reihenfolge vom Stärksten zum Schwächsten). Die Überschreibung muss gleich oder schwächer als die konfigurierte Konsistenzstufe des Kontos sein.

Die Konsistenzstufenüberschreibung für Leseoptionen für Dokumente und Anhänge. Die gültigen Werte sind: Stark, Begrenzt, Sitzung oder Eventuell (in der Reihenfolge vom Stärksten zum Schwächsten). Die Überschreibung muss gleich oder schwächer als die konfigurierte Konsistenzstufe des Kontos sein.

Arrays abflachen

Standardmäßig werden verschachtelte Arrays als JSON-Strings zurückgegeben. Mit der Eigenschaft FlattenArrays können die Elemente verschachtelter Arrays in eigene Spalten umgewandelt werden. Legen Sie FlattenArrays auf die Anzahl der Elemente fest, die Sie aus verschachtelten Arrays zurückgeben möchten.

Datentyp

string

Standardwert

0

Hinweise

Standardmäßig werden verschachtelte Arrays als JSON-Strings zurückgegeben. Das FlattenArrays-Eigenschaft kann verwendet werden, um die Elemente verschachtelter Arrays in eigene Spalten zu reduzieren. Dies wird nur für Arrays empfohlen, die voraussichtlich kurz sind.

Set FlattenArrays zur Anzahl der Elemente, die Sie aus verschachtelten Arrays zurückgeben möchten. Die angegebenen Elemente werden als Spalten zurückgegeben. Der nullbasierte Index wird an den Spaltennamen angehängt. Andere Elemente werden ignoriert.

Sie können beispielsweise eine beliebige Anzahl von Elementen aus einem Array von Zeichenfolgen zurückgeben:

["FLOW-MATIC","LISP","COBOL"]

Wenn FlattenArrays auf 1 gesetzt ist, wird das vorhergehende Array in die folgende Tabelle abgeflacht:

Einstellung FlattenArrays auf -1 reduziert alle Elemente verschachtelter Arrays.

Objekte abflachen

Setzen Sie FlattenObjects auf true, um Objekteigenschaften in eigene Spalten zu reduzieren. Andernfalls werden in Arrays verschachtelte Objekte als JSON-Strings zurückgegeben.

Datentyp

bool

Standardwert

true

Hinweise

Satz FlattenObjects auf true, um Objekteigenschaften in eigene Spalten zu reduzieren. Andernfalls werden in Arrays verschachtelte Objekte als JSON-Zeichenfolgen zurückgegeben. Der Eigenschaftsname wird mit einem Punkt an den Objektnamen angehängt, um den Spaltennamen zu generieren.

Sie können beispielsweise die folgenden verschachtelten Objekte zum Zeitpunkt der Verbindung reduzieren:

[
     { "grade": "A", "score": 2 },
     { "grade": "A", "score": 6 },
     { "grade": "A", "score": 10 },
     { "grade": "A", "score": 9 },
     { "grade": "B", "score": 14 }
]

Wenn FlattenObjects ist auf true gesetzt und FlattenArrays auf 1 gesetzt ist, wird das vorhergehende Array in die folgende Tabelle abgeflacht:

Abfrage bei nicht indizierten Containern erzwingen

Erzwingen Sie die Verwendung eines Index-Scans zur Verarbeitung der Abfrage, wenn die Indizierung deaktiviert ist oder der richtige Indexpfad nicht verfügbar ist.

Datentyp

bool

Standardwert

false

Hinweise

Abfragen von Containern, bei denen die Indizierung deaktiviert ist oder Pfade ausgeschlossen sind, können fehlschlagen. Setzen Sie diese Eigenschaft auf „true“, um die Verwendung der Indizierung auf dem Server zu erzwingen, damit die Abfrage erfolgreich verarbeitet wird. Standardmäßig werden Abfragen, die die Verwendung der Indizierung von Containern erfordern, bei denen „IndexingMode=None“ ist, clientseitig verarbeitet.

Schemadateien generieren

Gibt die Benutzerpräferenz an, wann Schemata generiert und gespeichert werden sollen.

Mögliche Werte

Never, OnUse, OnStart, OnCreate

Datentyp

string

Standardwert

Never

Hinweise

GenerateSchemaFiles ermöglicht das Speichern der von Automatic Schema Discovery identifizierten Tabellendefinitionen. Diese Eigenschaft gibt Schemas in .rsd-Dateien im durch Location angegebenen Pfad aus.

Die folgenden Einstellungen sind verfügbar:

• Niemals: Es wird nie eine Schema generiert.
• OnUse: Beim ersten Verweis auf eine Tabelle wird eine Schema generiert, sofern die Schema für die Tabelle noch nicht vorhanden ist.
• OnStart: Zum Zeitpunkt der Verbindung wird für alle Tabellen, die aktuell keine Schema haben, eine Schema generiert.
• OnCreate: Beim Ausführen einer CREATE TABLE-SQL- Abfrage wird eine Schema generiert.

Beachten Sie, dass Sie eine Datei zuerst löschen müssen, wenn Sie sie neu generieren möchten.

Generieren von Schemas mit SQL

Wenn Sie setzen GenerateSchemaFiles Zu OnUse, der Connector generiert Schemata, während Sie SELECT-Abfragen ausführen. Schemata werden für jede in der Abfrage referenzierte Tabelle generiert.

Wenn Sie setzen GenerateSchemaFiles Zu OnCreate, Schemas werden nur generiert, wenn eine CREATE TABLE Abfrage ausgeführt wird.

Schemas bei Verbindung generieren

Eine andere Möglichkeit, diese Eigenschaft zu verwenden, besteht darin, beim Herstellen einer Verbindung Schemata für jede Tabelle in Ihrer Datenbank abzurufen. Setzen Sie dazu GenerateSchemaFiles Zu OnStart und verbinden.

Alternativen zu statischen Schemas

Wenn Ihre Datenstrukturen volatil sind, sollten Sie Folgendes festlegen: GenerateSchemaFiles auf Nie und Verwendung dynamischer Schemata. Siehe Automatische Schemaerkennung für weitere Informationen zu dynamischen Schemata.

Bearbeiten von Schemas

Schemadateien haben ein einfaches Format, das ihre Änderung erleichtert. Siehe Benutzerdefinierte Schemadefinitionen für weitere Informationen.

MaxRows

Begrenzt die Anzahl der zurückgegebenen Zeilen, wenn in der Abfrage keine Aggregation oder GROUP BY verwendet wird. Dies hat Vorrang vor LIMIT-Klauseln.

Datentyp

int

Standardwert

-1

Hinweise

Begrenzt die Anzahl der zurückgegebenen Zeilen, wenn in der Abfrage keine Aggregation oder GROUP BY verwendet wird. Dies hat Vorrang vor LIMIT-Klauseln.

MaxThreads

Gibt die maximale Anzahl gleichzeitiger Anfragen für Batch-CUD-Vorgänge (Erstellen, Aktualisieren, Löschen) an.

Datentyp

int

Standardwert

200

Hinweise

Diese Eigenschaft sollte in Verbindung mit dem WriteThroughputBudget verwendet werden Verbindungseigenschaft. Der Connector kann weniger parallele Anfragen ausführen als die konfigurierte MaxThreads-Wert, da immer das Ziel besteht, das WriteThroughputBudget nicht zu überschreiten-Limit. Die Anzahl gleichzeitiger Anfragen hängt auch von den Ressourcen der laufenden Maschine ab.

MultiThreadCount

Aggregatabfragen in partitionierten Sammlungen erfordern parallele Anfragen für verschiedene Partitionsbereiche. Stellen Sie dies auf die Anzahl der parallelen Anfragen ein, die gleichzeitig ausgegeben werden sollen.

Datentyp

string

Standardwert

5

Hinweise

Aggregatabfragen in partitionierten Sammlungen erfordern parallele Anfragen für verschiedene Partitionsbereiche. Stellen Sie dies auf die Anzahl der parallelen Anfragen ein, die gleichzeitig ausgegeben werden sollen.

Andere

Diese versteckten Eigenschaften werden nur in bestimmten Anwendungsfällen verwendet.

Datentyp

string

Standardwert

""

Hinweise

Die unten aufgeführten Eigenschaften sind für bestimmte Anwendungsfälle verfügbar. Für normale Anwendungsfälle und Funktionen von Treiber sollten diese Eigenschaften nicht erforderlich sein.

Geben Sie mehrere Eigenschaften in einer durch Semikolon getrennten Liste an.

Integration und Formatierung

Seitengröße

Die maximale Anzahl von Ergebnissen, die pro Seite von Azure Cosmos DB zurückgegeben werden sollen.

Datentyp

int

Standardwert

1000

Hinweise

Der Pagesize Die Eigenschaft beeinflusst die maximale Anzahl von Ergebnissen, die pro Seite von Azure Cosmos DB zurückgegeben werden. Das Festlegen eines höheren Werts kann zu einer besseren Leistung führen, allerdings auf Kosten des zusätzlichen Speichers, der pro verbrauchter Seite zugewiesen wird.

Pseudospalten

Diese Eigenschaft gibt an, ob Pseudospalten als Spalten in die Tabelle aufgenommen werden sollen oder nicht.

Datentyp

string

Standardwert

""

Hinweise

Diese Einstellung ist besonders hilfreich im Entity Framework, da Sie dort keinen Wert für eine Pseudospalte festlegen können, es sei denn, es handelt sich um eine Tabellenspalte. Der Wert dieser Verbindungseinstellung hat das Format „Tabelle1=Spalte1, Tabelle1=Spalte2, Tabelle2=Spalte3“. Sie können das Zeichen „*“ verwenden, um alle Tabellen und alle Spalten einzuschließen, z. B. „*=*“.

Anforderungsprioritätsstufe

Gibt die Priorität für die an Azure Cosmos DB gesendete Anforderung an, wenn mehr Anforderungen als die konfigurierten RU/s pro Sekunde vorliegen.

Mögliche Werte

None, Low, High

Datentyp

string

Standardwert

None

Hinweise

• Keine: Legen Sie dies fest, um Anfragen mit der Standardpriorität zu senden.

• Niedrig: Legen Sie dies fest, um Anfragen mit niedriger Priorität zu senden.

• Hoch: Legen Sie dies fest, um Anfragen mit hoher Priorität zu senden.

Zeilenscantiefe

Die maximale Anzahl zu scannender Zeilen, um nach den in einer Tabelle verfügbaren Spalten zu suchen.

Datentyp

int

Standardwert

100

Hinweise

Die Spalten in einer Tabelle müssen durch das Scannen der Tabellenzeilen ermittelt werden. Dieser Wert bestimmt die maximale Anzahl der zu scannenden Zeilen.

Das Festlegen eines hohen Wertes kann die Leistung beeinträchtigen. Das Festlegen eines niedrigen Wertes kann dazu führen, dass der Datentyp nicht richtig ermittelt wird, insbesondere wenn Nulldaten vorhanden sind.

Trennzeichen

Das oder die Zeichen, die zur Bezeichnung der Hierarchie verwendet werden.

Datentyp

string

Standardwert

.

Hinweise

Um hierarchische Strukturen abzuflachen, benötigt der Connector einen Spezifizierer, der den Pfad zu einer Spalte durch die Hierarchie angibt. Wenn dieser Wert „.“ lautet und eine Spalte mit dem Namen Adresse.Stadt zurückgegeben wird, deutet dies darauf hin, dass es ein zugeordnetes Attribut mit einem untergeordneten Attribut namens Stadt gibt. Wenn Ihre Daten Spalten enthalten, die bereits einen einzelnen Punkt im Attributnamen verwenden, setzen Sie das SeparatorCharacter zu einem oder mehreren anderen Charakteren.

PartitionKeyAsPK festlegen

Ob das Partitionsschlüsselfeld der Sammlung als Teil des zusammengesetzten Primärschlüssels für die entsprechende freigegebene Tabelle verwendet werden soll oder nicht.

Datentyp

bool

Standardwert

true

Hinweise

Standardmäßig ist dies auf TRUE eingestellt und der Partitionsschlüssel der Sammlung wird zusammen mit der Spalte _rid als Teil des zusammengesetzten Primärschlüssels der Tabelle verwendet. Wenn dies auf FALSE eingestellt ist, dient nur die Spalte _rid als Primärschlüssel für die freigegebene Tabelle.

Zeitüberschreitung

Der Wert in Sekunden, bis der Timeout-Fehler auftritt und der Operation abgebrochen wird.

Datentyp

int

Standardwert

60

Hinweise

Wenn Timeout = 0, Operationen werden nicht abgebrochen. Die Operationen werden ausgeführt, bis sie erfolgreich abgeschlossen sind oder bis ein Fehler auftritt.

Wenn Timeout abläuft und der Operation noch nicht abgeschlossen ist, löst der Connector eine Ausnahme aus.

Typerkennungsschema

Durch Kommas getrennte Optionen, wie der Anbieter die Daten scannt, um die Felder und Datentypen in jeder Dokumentsammlung zu bestimmen.

Datentyp

string

Standardwert

RowScan,Recent

Hinweise

BenutzerdefinierteAnsichten

Ein Dateipfad, der auf die JSON-Konfigurationsdatei verweist, die Ihre benutzerdefinierten Ansichten enthält.

Datentyp

string

Standardwert

""

Hinweise

Benutzerdefinierte Ansichten werden in einer JSON-formatierten Konfigurationsdatei namens UserDefinedViews.json. Der Connector erkennt die in dieser Datei angegebenen Ansichten automatisch.

Sie können auch mehrere Ansichtsdefinitionen haben und diese mit steuern UserDefinedViews Verbindungseigenschaft. Wenn Sie diese Eigenschaft verwenden, werden vom Connector nur die angegebenen Ansichten angezeigt.

Diese Konfigurationsdatei für benutzerdefinierte Ansichten ist wie folgt formatiert:

• Jedes Stammelement definiert den Namen einer Ansicht.
• Jedes Stammelement enthält ein untergeordnetes Element namens query, das die benutzerdefinierte SQL- Abfrage für die Ansicht enthält.

Zum Beispiel:

{
    "MyView": {
        "query": "SELECT * FROM [].[Entities].Customers WHERE MyColumn = 'value'"
    },
    "MyView2": {
        "query": "SELECT * FROM MyTable WHERE Id IN (1,2,3)"
    }
}

Verwenden Sie UserDefinedViews Verbindungseigenschaft, um den Speicherort Ihrer JSON-Konfigurationsdatei anzugeben. Beispiel:

"UserDefinedViews", C:\Users\yourusername\Desktop\tmp\UserDefinedViews.json

Beachten Sie, dass der angegebene Pfad nicht in Anführungszeichen steht.

Verwenden SieRidAsPk

Setzen Sie diese Eigenschaft auf „false“, um die ID-Spalte als Primärschlüssel anstelle der Standard-_rid zu verwenden.

Datentyp

bool

Standardwert

true

Hinweise

Da CosmosDB Ihnen erlaubt, sowohl _rid- als auch ID-Felder als eindeutige Werte zum Abrufen von Ressourcendaten zu verwenden, können Sie diese Eigenschaft auf „false“ setzen, um die ID-Spalte als Primärschlüssel anstelle der Standard-_rid zu verwenden.

SchreibDurchsatzBudget

Definiert das Budget für Anforderungseinheiten (RU) pro Sekunde, das die Batch-CUD-Vorgänge (Erstellen, Aktualisieren, Löschen) nicht überschreiten sollten.

Datentyp

int

Standardwert

1000

Hinweise

Der Connector passt die maximale Anzahl von Anfragen pro Sekunde dynamisch an, abhängig vom konfigurierten RU-Budget. Obwohl der Connector immer versucht, das RU-Budget nicht zu überschreiten, kann es in einigen Fällen zu einer relativ geringen Überschreitung kommen, da die drosselung clientseitig angewendet wird. Zu diesen Fällen gehören das Einfügen, Aktualisieren und Löschen von Datensätzen mit stark variabler Spaltenanzahl und Eingabewertlänge pro Spalte.