Herstellen einer Verbindung mit Azure KI-Suche mithilfe von Schlüsseln
Azure KI-Suche bietet eine schlüsselbasierte Authentifizierung für Verbindungen mit Ihrem Suchdienst. Ein API-Schlüssel ist eine einzigartige Zeichenfolge aus 52 zufällig generierten Ziffern und Buchstaben. Im Quellcode können Sie sie als Umgebungsvariable oder als App-Einstellung in Ihrem Projekt angeben und dann auf die Variable für die Anforderung verweisen. Eine Anforderung an einen Suchdienstendpunkt wird akzeptiert, wenn sowohl die Anforderung als auch der API-Schlüssel gültig sind.
Die schlüsselbasierte Authentifizierung ist der Standard.
Sie können sie durch rollenbasierten Zugriff ersetzen, wodurch die Notwendigkeit hartcodierter Schlüssel in Ihrer Codebasis entfällt.
Typen von API-Schlüsseln
Es gibt zwei Arten von Schlüsseln, die für die Authentifizierung einer Anforderung verwendet werden:
| Typ | Berechtigungsstufe | Maximum | So wird's erstellt |
|---|---|---|---|
| Administrator | Vollzugriff (Lese-/Schreibzugriff) für alle Inhaltsvorgänge | 2 1 | Für Administratoren werden zwei Schlüssel generiert, wenn der Dienst erstellt wird. Diese werden im Azure-Portal als primärer bzw. sekundärer Schlüssel bezeichnet und können bei Bedarf einzeln neu generiert werden. |
| Abfrage | Schreibgeschützter Zugriff, der auf die Dokumentensammlung eines Suchindex festgelegt ist | 50 | Ein Abfrageschlüssel wird mit dem Dienst generiert. Mehr können bei Bedarf von einem Suchdienstadministrator erstellt werden. |
1 Durch die Verwendung von zwei Schlüsseln kann weiterhin auf den Dienst zugegriffen werden, während für einen der Schlüssel ein Rollover durchgeführt wird.
Administrator- und Abfrageschlüssel sind rein optisch nicht zu unterscheiden. Bei beiden Schlüsseln handelt es sich um eine Zeichenfolge mit 52 nach dem Zufallsprinzip generierten alphanumerischen Zeichen. Sollten Sie nicht mehr wissen, welche Art von Schlüssel in Ihrer Anwendung angegeben ist, können Sie die Schlüsselwerte im Azure-Portal überprüfen.
Verwenden von API-Schlüsseln für Verbindungen
API-Schlüssel werden für Datenebenenanforderungen (Inhaltsanforderungen) verwendet, z. B. zum Erstellen oder Zugreifen auf einen Index oder eine andere Anforderung, die in den Search REST-APIs dargestellt wird. Bei der Diensterstellung ist ein API-Schlüssel der einzige Authentifizierungsmechanismus für Datenebenenvorgänge, Sie können die Schlüsselauthentifizierung jedoch durch Azure-Rollen ersetzen oder ergänzen, wenn Sie in Ihrem Code keine hartcodierten Schlüssel verwenden können.
Administratorschlüssel werden zum Erstellen, Ändern oder Löschen von Objekten verwendet. Administratorschlüssel werden auch für GET-Objektdefinitionen und Systeminformationen verwendet.
Abfrageschlüssel werden in der Regel an Clientanwendungen verteilt, die Abfragen ausgeben.
Verwendung von API-Schlüsseln in REST-Aufrufen:
Legen Sie einen Administratorschlüssel im Anforderungsheader fest. Sie können keine Administratorschlüssel für den URI oder im Textkörper der Anforderung übergeben. Administratorschlüssel werden für den Erstellen-Lesen-Aktualisieren-Löschen-Vorgang und für Anforderungen verwendet, die an den Suchdienst selbst ausgestellt wurden, wie z. B. LIST-Indizes oder Abrufen von Dienststatistiken.
Hier finden Sie ein Beispiel für die Verwendung des Administrator-API-Schlüssels für eine Anforderung zum Erstellen eines Indexes:
### Create an index
POST {{baseUrl}}/indexes?api-version=2024-07-01 HTTP/1.1
Content-Type: application/json
api-key: {{adminApiKey}}
{
"name": "my-new-index",
"fields": [
{"name": "docId", "type": "Edm.String", "key": true, "filterable": true},
{"name": "Name", "type": "Edm.String", "searchable": true }
]
}
Legen Sie einen Abfrageschlüssel in einem Anforderungsheader für POST fest oder im URI für GET. Abfrageschlüssel werden für Vorgänge verwendet, die auf die index/docs-Sammlung abzielen: Dokumente durchsuchen, Autovervollständigen, Vorschlag oder Dokument abrufen.
Nachfolgend finden Sie ein Beispiel für die Verwendung von API-Schlüsseln für eine Anforderung zum Durchsuchen von Dokumenten:
### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}
Hinweis
Aus Sicherheitsgründen sollten im Anforderungs-URI keine vertraulichen Daten wie etwa ein API-Schlüssel (api-key) übergeben werden. Aus diesem Grund akzeptiert Azure AI Search nur einen Abfrageschlüssel als api-key in der Abfragezeichenfolge. Wir empfehlen generell, api-key als Anforderungsheader zu übergeben.
Berechtigungen zum Anzeigen oder Verwalten von API-Schlüsseln
Berechtigungen zum Anzeigen und Verwalten von API-Schlüsseln werden über Rollenzuweisungenvermittelt. Mitglieder der folgenden Rollen können Schlüssel anzeigen und erneut generieren:
- Besitzer
- Mitwirkender
- Mitwirkender von Suchdienst
- Administrator und Co-Administrator (klassisch)
Die folgenden Rollen haben keinen Zugriff auf API-Schlüssel:
- Leser
- Mitwirkender an Suchindexdaten
- Suchindexdatenleser
Suchen vorhandener Schlüssel
Sie können API-Schlüssel im Azure-Portal oder über PowerShell, Azure CLI oder REST-API anzeigen und verwalten.
Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter Einstellungen die Option Schlüssel aus, um Administrator- und Abfrageschlüssel anzuzeigen.
Erstellen von Abfrageschlüsseln
Abfrageschlüssel werden für den schreibgeschützten Zugriff auf Dokumente in einem Index für die Vorgänge für eine Dokumentensammlung verwendet. Such-, Filter- und Vorschlagsabfragen sind Vorgänge, die einen Abfrageschlüssel verwenden. Alle schreibgeschützten Vorgänge, die Systemdaten oder Objektdefinitionen zurückgeben, z. B. eine Indexdefinition oder einen Indexerstatus, erfordern einen Administratorschlüssel.
Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist besonders wichtig, um die Suchobjekte in Ihrem Dienst zu schützen. Verwenden Sie für Abfragen aus einer Client-App immer einen Abfrageschlüssel anstelle eines Administratorschlüssels.
Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter Einstellungen die Option Schlüssel aus, um API-Schlüssel anzuzeigen.
Verwenden Sie unter Abfrageschlüssel verwalten den für Ihren Dienst bereits generierten Abfrageschlüssel, oder erstellen Sie neue Abfrageschlüssel. Der Standardabfrageschlüssel ist nicht benannt, aber andere generierte Abfrageschlüssel können zur Verwaltbarkeit benannt werden.
Erneutes Generieren von Administratorschlüsseln
Für jeden Dienst werden zwei Administratorschlüssel erstellt, sodass Sie einen Primärschlüssel rotieren können, während Sie einen Sekundärschlüssel für Geschäftskontinuität verwenden.
Wählen Sie unter Einstellungen die Option Schlüssel aus, und kopieren Sie dann den sekundären Schlüssel.
Aktualisieren Sie für alle Anwendungen die Einstellungen des API-Schlüssels so, dass der Sekundärschlüssel verwendet wird.
Generieren Sie den Primärschlüssel neu.
Aktualisieren Sie alle Anwendungen so, dass sie den neuen Primärschlüssel verwenden.
Wenn Sie versehentlich beide Schlüssel gleichzeitig neu generieren, wird für alle Clientanforderungen, die diese Schlüssel verwenden, der Fehler „HTTP 403 – Verboten“ zurückgegeben. Inhalte werden jedoch nicht gelöscht und Sie werden nicht dauerhaft gesperrt.
Sie können weiterhin über das Azure-Portal oder programmgesteuert auf den Dienst zugreifen. Verwaltungsfunktionen werden über eine Abonnement-ID und nicht einen Dienst-API-Schlüssel verwendet und sind daher auch dann verfügbar, wenn Ihre API-Schlüssel nicht verfügbar sind.
Nach der Erstellung neuer Schlüssel über das Portal oder die Verwaltungsebene wird der Zugriff auf Ihre Inhalte (Indizes, Indexer, Datenquellen, Synonymzuordnungen) wiederhergestellt, sobald Sie die neuen Schlüssel haben und nach Aufforderung angeben.
Sichern von API-Schlüsseln
Verwenden Sie Rollenzuweisungen, um den Zugriff auf API-Schlüssel einzuschränken.
Es ist nicht möglich, die Verschlüsselung durch kundenseitig verwaltete Schlüssel zum Verschlüsseln von API-Schlüsseln zu verwenden. Nur vertrauliche Daten innerhalb des Suchdienstes selbst (z. B. Indexinhalt oder Verbindungszeichenfolgen in Datenquellenobjektdefinitionen) können CMK-verschlüsselt werden.
Navigieren Sie im Azure-Portal zur Seite Ihres Suchdiensts.
Wählen Sie im linken Navigationsbereich Zugriffssteuerung (IAM) und anschließend die Registerkarte Rollenzuweisungen aus.
Wählen Sie im Rollenfilter die Rollen aus, die über die Berechtigung zum Anzeigen oder Verwalten von Schlüsseln verfügen (Besitzer, Mitwirkender, Suchdienstmitwirkender). Die resultierenden Sicherheitsprinzipale, die diesen Rollen zugewiesen sind, verfügen über Schlüsselberechtigungen für Ihren Suchdienst.
Überprüfen Sie als Vorsichtsmaßnahme auch die Registerkarte Klassische Administratoren, um festzustellen, ob Administratoren und Co-Administratoren Zugriff haben.
Bewährte Methoden
Verwenden Sie API-Schlüssel nur, wenn die Offenlegung von Daten kein Risiko ist (z. B. bei Verwendung von Beispieldaten) und wenn Sie hinter einer Firewall arbeiten. Die Offenlegung von API-Schlüsseln ist ein Risiko für Daten sowie für die nicht autorisierte Verwendung Ihres Suchdiensts.
Überprüfen Sie Ihren Code vor der Veröffentlichung von Beispielen und Schulungsmaterialien immer, um sicherzustellen, dass Sie keine gültigen API-Schlüssel hinterlassen haben.
Wechseln Sie für Produktionsworkloads zu Microsoft Entra ID und rollenbasiertem Zugriff. Oder, wenn Sie auch weiterhin API-Schlüssel verwenden möchten, sollten Sie auch immer überwachen, wer Zugriff auf Ihre API-Schlüssel hat, und API-Schlüssel in regelmäßigen Abständen neu generieren.