Erstellen und Verwalten von API-Schlüsseln für einen Azure Search-DienstCreate and manage api-keys for an Azure Search service

Für alle Anforderungen an einen Suchdienst wird ein schreibgeschützter API-Schlüssel benötigt, der speziell für Ihren Dienst generiert wurde.All requests to a search service need a read-only api-key that was generated specifically for your service. Dieser API-Schlüssel ist der einzige Authentifizierungsmechanismus für den Zugriff auf Ihren Suchdienstendpunkt und muss in jede Anforderung einbezogen werden.The api-key is the sole mechanism for authenticating access to your search service endpoint and must be included on every request. In REST-Lösungen wird der API-Schlüssel in der Regel im Anforderungsheader angegeben.In REST solutions, the api-key is typically specified in a request header. In .NET-Lösungen wird ein Schlüssel häufig als Konfigurationseinstellung angegeben und dann in Form von Credentials (Administratorschlüssel) oder SearchCredentials (Abfrageschlüssel) auf dem SearchServiceClient übergeben.In .NET solutions, a key is often specified as a configuration setting and then passed as Credentials (admin key) or SearchCredentials (query key) on SearchServiceClient.

Schlüssel werden während der Dienstbereitstellung mit dem Suchdienst erstellt.Keys are created with your search service during service provisioning. Sie können Schlüsselwerte im Azure-Portal anzeigen und abrufen.You can view and obtain key values in the Azure portal.

Portalseite > „Einstellungen“ > Abschnitt „Schlüssel“

Was ist ein API-Schlüssel?What is an api-key

Ein API-Schlüssel ist eine Zeichenfolge, die aus zufällig generierten Zahlen und Buchstaben besteht.An api-key is a string composed of randomly generated numbers and letters. Durch rollenbasierte Berechtigungen können Sie die Schlüssel löschen oder lesen, aber Sie können einen Schlüssel nicht durch ein benutzerdefiniertes Kennwort ersetzen oder Active Directory als primäre Authentifizierungsmethode für den Zugriff auf Suchvorgänge verwenden.Through role-based permissions, you can delete or read the keys, but you can't replace a key with a user-defined password or use Active Directory as the primary authentication methodology for accessing search operations.

Zwei Arten von Schlüsseln werden für den Zugriff auf Ihren Suchdienst verwendet: Administrator (Lesen/Schreiben) und Abfrage (schreibgeschützt).Two types of keys are used to access your search service: admin (read-write) and query (read-only).

SchlüsselKey BESCHREIBUNGDescription EinschränkungenLimits
AdministratorAdmin Gewährt Vollzugriff auf alle Vorgänge. Dazu zählen die Dienstverwaltung sowie das Erstellen und Löschen von Indizes, Indexern und Datenquellen.Grants full rights to all operations, including the ability to manage the service, create and delete indexes, indexers, and data sources.

Für Administratoren werden zwei Schlüssel generiert, wenn der Dienst erstellt wird. Diese werden im Portal als primärer bzw. sekundärer Schlüssel bezeichnet und können bei Bedarf einzeln neu generiert werden.Two admin keys, referred to as primary and secondary keys in the portal, are generated when the service is created and can be individually regenerated on demand. 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.Having two keys allows you to roll over one key while using the second key for continued access to the service.

Administratorschlüssel werden nur in HTTP-Anforderungsheadern angegeben.Admin keys are only specified in HTTP request headers. Ein API-Schlüssel für Administratoren kann nicht in einer URL platziert werden.You cannot place an admin api-key in a URL.
Maximal zwei pro DienstMaximum of 2 per service
AbfragenQuery Gewährt Lesezugriff auf Indizes und Dokumente. Diese werden in der Regel auf Clientanwendungen verteilt, die Suchanfragen ausgeben.Grants read-only access to indexes and documents, and are typically distributed to client applications that issue search requests.

Abfrageschlüssel werden bei Bedarf erstellt.Query keys are created on demand. Sie können manuell über das Portal oder programmgesteuert über die Verwaltungs-REST-API erstellt werden.You can create them manually in the portal or programmatically via the Management REST API.

Abfrageschlüssel können in einem HTTP-Anforderungsheader für Such-, Vorschlags- oder Recherchevorgänge angegeben werden.Query keys can be specified in an HTTP request header for search, suggestion, or lookup operation. Sie können einen Abfrageschlüssel aber auch als Parameter in einer URL übergeben.Alternatively, you can pass a query key as a parameter on a URL. Je nachdem, wie Ihre Clientanwendung die Anforderung formuliert, ist es unter Umständen einfacher, den Schlüssel als Abfrageparameter zu übergeben:Depending on how your client application formulates the request, it might be easier to pass the key as a query parameter:

GET /indexes/hotels/docs?search=*&$orderby=lastRenovationDate desc&api-version=2019-05-06&api-key=[query key]
50 pro Dienst50 per service

Administrator- und Abfrageschlüssel sind rein optisch nicht zu unterscheiden.Visually, there is no distinction between an admin key or query key. Bei beiden Schlüsseln handelt es sich um eine Zeichenfolge mit 32 nach dem Zufallsprinzip generierten alphanumerischen Zeichen.Both keys are strings composed of 32 randomly generated alpha-numeric characters. Sollten Sie nicht mehr wissen, welche Art von Schlüssel in Ihrer Anwendung angegeben ist, können Sie die Schlüsselwerte im Portal überprüfen oder über die REST-API den Wert und die Art des Schlüssels zurückgeben.If you lose track of what type of key is specified in your application, you can check the key values in the portal or use the REST API to return the value and key type.

Hinweis

Aus Sicherheitsgründen sollten im Anforderungs-URI keine vertraulichen Daten wie etwa ein API-Schlüssel (api-key) übergeben werden.It is considered a poor security practice to pass sensitive data such as an api-key in the request URI. Aus diesem Grund akzeptiert Azure Search als api-key in der Abfragezeichenfolge nur einen Abfrageschlüssel. Es empfiehlt sich, diese Richtlinie einzuhalten – es sei denn, der Inhalt Ihres Index soll öffentlich verfügbar sein.For this reason, Azure Search only accepts a query key as an api-key in the query string, and you should avoid doing so unless the contents of your index should be publicly available. Wir empfehlen generell, api-key als Anforderungsheader zu übergeben.As a general rule, we recommend passing your api-key as a request header.

Suchen vorhandener SchlüsselFind existing keys

Zugriffsschlüssel stehen über das Portal oder über die Verwaltungs-REST-API zur Verfügung.You can obtain access keys in the portal or through the Management REST API. Weitere Informationen finden Sie unter Verwalten der Administrator- und Abfrage-API-Schlüssel.For more information, see Manage admin and query api-keys.

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Listen Sie die Suchdienste für Ihr Abonnement auf.List the search services for your subscription.

  3. Wählen Sie den Dienst aus, und klicken Sie auf der Seite „Übersicht“ auf Einstellungen >Schlüssel, um Administrator- und Abfrageschlüssel anzuzeigen.Select the service and on the Overview page, click Settings >Keys to view admin and query keys.

    Portalseite > „Einstellungen“ > Abschnitt „Schlüssel“

Erstellen von AbfrageschlüsselnCreate query keys

Abfrageschlüssel werden für den schreibgeschützten Zugriff auf Dokumente in einem Index für die Vorgänge für eine Dokumentensammlung verwendet.Query keys are used for read-only access to documents within an index for operations targeting a documents collection. Such-, Filter- und Vorschlagsabfragen sind Vorgänge, die einen Abfrageschlüssel verwenden.Search, filter, and suggestion queries are all operations that take a query key. Alle schreibgeschützten Vorgänge, die Systemdaten oder Objektdefinitionen zurückgeben, z. B. eine Indexdefinition oder einen Indexerstatus, erfordern einen Administratorschlüssel.Any read-only operation that returns system data or object definitions, such as an index definition or indexer status, requires an admin key.

Das Einschränken des Zugriffs und der Vorgänge in Client-Apps ist besonders wichtig, um die Suchobjekte in Ihrem Dienst zu schützen.Restricting access and operations in client apps is essential to safeguarding the search assets on your service. Verwenden Sie für Abfragen aus einer Client-App immer einen Abfrageschlüssel anstelle eines Administratorschlüssels.Always use a query key rather than an admin key for any query originating from a client app.

  1. Melden Sie sich beim Azure-Portal an.Sign in to the Azure portal.

  2. Listen Sie die Suchdienste für Ihr Abonnement auf.List the search services for your subscription.

  3. Wählen Sie den Dienst aus, und klicken Sie auf der Seite „Übersicht“ auf Einstellungen >Schlüssel.Select the service and on the Overview page, click Settings >Keys.

  4. Klicken Sie auf Abfrageschlüssel verwalten.Click Manage query keys.

  5. Verwenden Sie einen bereits für Ihren Dienst generierten Abfrageschlüssel, oder erstellen Sie bis zu 50 neue Abfrageschlüssel.Use the query key already generated for your service, or create up to 50 new query keys. Der Standardabfrageschlüssel ist nicht benannt. Sie können zusätzliche Abfrageschlüssel jedoch für eine einfachere Verwaltbarkeit benennen.The default query key is not named, but additional query keys can be named for manageability.

    Erstellen oder Verwenden von Abfrageschlüsseln

Hinweis

Ein Codebeispiel für die Verwendung von Abfrageschlüsseln finden Sie in Abfragen eines Azure Search-Index in C#.A code example showing query key usage can be found in Query an Azure Search index in C#.

Erneutes Generieren von AdministratorschlüsselnRegenerate admin keys

Für jeden Dienst werden zwei Administratorschlüssel erstellt, sodass Sie einen Primärschlüssel mit dem Sekundärschlüssel für Geschäftskontinuität rotieren können.Two admin keys are created for each service so that you can rotate a primary key, using the secondary key for business continuity.

  1. Kopieren Sie den Sekundärschlüssel auf der Seite Einstellungen >Schlüssel.In the Settings >Keys page, copy the secondary key.
  2. Aktualisieren Sie für alle Anwendungen die Einstellungen des API-Schlüssels so, dass der Sekundärschlüssel verwendet wird.For all applications, update the api-key settings to use the secondary key.
  3. Generieren Sie den Primärschlüssel neu.Regenerate the primary key.
  4. Aktualisieren Sie alle Anwendungen so, dass sie den neuen Primärschlüssel verwenden.Update all applications to use the new primary key.

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.If you inadvertently regenerate both keys at the same time, all client requests using those keys will fail with HTTP 403 Forbidden. Allerdings werden die Inhalte nicht gelöscht, und Sie sind nicht dauerhaft gesperrt.However, content is not deleted and you are not locked out permanently.

Sie können weiterhin über das Portal oder die Verwaltungsebene (REST-API, PowerShell oder Azure Resource Manager) auf den Dienst zugreifen.You can still access the service through the portal or the management layer (REST API, PowerShell, or Azure Resource Manager). 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.Management functions are operative through a subscription ID not a service api-key, and thus still available even if your api-keys are not.

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.After you create new keys via portal or management layer, access is restored to your content (indexes, indexers, data sources, synonym maps) once you have the new keys and provide those keys on requests.

Sichern von API-SchlüsselnSecure api-keys

Die Sicherheit der Schlüssel wird erreicht, indem der Zugriff über das Portal oder Resource Manager-Oberflächen (PowerShell oder Befehlszeilenschnittstelle) eingeschränkt wird.Key security is ensured by restricting access via the portal or Resource Manager interfaces (PowerShell or command-line interface). Wie bereits erwähnt, können Abonnementadministratoren alle API-Schlüssel anzeigen und neu generieren.As noted, subscription administrators can view and regenerate all api-keys. Informieren Sie sich über Rollenzuweisungen, damit Sie wissen, wer Zugriff auf die Admin-Schlüssel hat.As a precaution, review role assignments to understand who has access to the admin keys.

  • Klicken Sie im Dashboard für den Dienst auf Zugriffssteuerung (IAM) und anschließend auf die Registerkarte Rollenzuweisungen, um die Rollenzuweisungen für Ihren Dienst anzuzeigen.In the service dashboard, click Access control (IAM) and then the Role assignments tab to view role assignments for your service.

Mitglieder der folgenden Rollen können Schlüssel anzeigen und erneut generieren: Besitzer, Mitwirkender und SuchdienstmitwirkenderMembers of the following roles can view and regenerate keys: Owner, Contributor, Search Service Contributors

Hinweis

Für den identitätsbasierten Zugriff über Suchergebnisse können Sie Sicherheitsfilter erstellen, um die Ergebnisse anhand der Identität einzugrenzen. Auf diese Weise werden Dokumente entfernt, auf die der Anforderer keinen Zugriff haben sollte.For identity-based access over search results, you can create security filters to trim results by identity, removing documents for which the requestor should not have access. Weitere Informationen finden Sie unter Sicherheitsfilter und Sichern mit Active Directory.For more information, see Security filters and Secure with Active Directory.

Weitere InformationenSee also