Verbinding maken met Azure AI Search met behulp van sleutels

Artikel
10/30/2024

Azure AI Search biedt verificatie op basis van sleutels voor verbindingen met uw zoekservice. Een API-sleutel is een unieke tekenreeks die bestaat uit 52 willekeurig gegenereerde cijfers en letters. In uw broncode kunt u deze opgeven als een omgevingsvariabele of als app-instelling in uw project en vervolgens verwijzen naar de variabele in de aanvraag. Een aanvraag die is ingediend bij een eindpunt van de zoekservice wordt geaccepteerd als zowel de aanvraag als de API-sleutel geldig zijn.

Verificatie op basis van sleutels is de standaardinstelling.

U kunt deze vervangen door op rollen gebaseerde toegang, waardoor de noodzaak voor in codebasis vastgelegde sleutels niet meer nodig is.

Typen API-sleutels

Er zijn twee soorten sleutels die worden gebruikt voor het verifiëren van een aanvraag:

Type	Machtigingsniveau	Maximum	Hoe gemaakt
Beheerder	Volledige toegang (lezen/schrijven) voor alle inhoudsbewerkingen	2 ¹	Twee beheerderssleutels, die in de portal primaire en secundaire sleutels worden genoemd, worden gegenereerd wanneer de service wordt gemaakt en kunnen op aanvraag afzonderlijk opnieuw worden gegenereerd.
Query	Alleen-lezentoegang, beperkt tot de documentenverzameling van een zoekindex	50	Er wordt één querysleutel gegenereerd met de service. Meer kunnen op aanvraag worden gemaakt door een zoekservicebeheerder.

¹ Met twee kunt u één sleutel overrollen terwijl u de tweede sleutel gebruikt voor continue toegang tot de service.

Visueel is er geen onderscheid tussen een beheersleutel of querysleutel. Beide sleutels zijn tekenreeksen die bestaan uit 52 willekeurig gegenereerde alfanumerieke tekens. Als u niet meer weet welk type sleutel is opgegeven in uw toepassing, kunt u de sleutelwaarden in de portal controleren.

API-sleutels gebruiken voor verbindingen

API-sleutels worden gebruikt voor aanvragen voor het gegevensvlak (inhoud), zoals het maken of openen van een index of een andere aanvraag die wordt weergegeven in de REST API's van Search. Bij het maken van een service is een API-sleutel het enige verificatiemechanisme voor gegevensvlakbewerkingen, maar u kunt sleutelverificatie vervangen of aanvullen met Azure-rollen als u geen in code vastgelegde sleutels in uw code kunt gebruiken.

Beheerderssleutels worden gebruikt voor het maken, wijzigen of verwijderen van objecten. Beheerderssleutels worden ook gebruikt voor GET-objectdefinities en systeeminformatie.

Querysleutels worden doorgaans gedistribueerd naar clienttoepassingen die query's uitgeven.

Hoe API-sleutels worden gebruikt in REST-aanroepen:

Stel een beheerderssleutel in de aanvraagheader in. U kunt geen beheerderssleutels doorgeven aan de URI of in de hoofdtekst van de aanvraag. Beheerderssleutels worden gebruikt voor het maken en bijwerken en verwijderen van aanvragen die zijn uitgegeven aan de zoekservice zelf, zoals LIST Indexen of GET-servicestatistieken.

Hier volgt een voorbeeld van het gebruik van beheerders-API-sleutels voor een indexaanvraag maken:

### 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 }
         ]
   }

Stel een querysleutel in een aanvraagheader in voor POST of op de URI voor GET. Querysleutels worden gebruikt voor bewerkingen die gericht zijn op de index/docs verzameling: Documenten doorzoeken, Automatisch aanvullen, Voorstellen of GET-document.

Hier volgt een voorbeeld van het gebruik van query-API-sleutels voor een GET-aanvraag (Search Documents):

### Query an index
GET /indexes/my-new-index/docs?search=*&api-version=2024-07-01&api-key={{queryApiKey}}

Notitie

Het wordt beschouwd als een slechte beveiligingspraktijk om gevoelige gegevens, zoals een api-key in de aanvraag-URI, door te geven. Daarom accepteert Azure AI Search alleen een querysleutel als een api-key in de querytekenreeks. Als algemene regel raden we u aan om uw api-key als aanvraagheader door te geven.

Hoe API-sleutels worden gebruikt in PowerShell:

Stel API-sleutels in de aanvraagheader in met behulp van de volgende syntaxis:

$headers = @{
'api-key' = '<YOUR-ADMIN-OR-QUERY-API-KEY>'
'Content-Type' = 'application/json' 
'Accept' = 'application/json' }

Een voorbeeld van een script met api-sleutelgebruik voor verschillende bewerkingen vindt u in quickstart: Een Azure AI Search-index maken in PowerShell met behulp van REST API's.

Machtigingen voor het weergeven of beheren van API-sleutels

Machtigingen voor het weergeven en beheren van API-sleutels worden overgebracht via roltoewijzingen. Leden van de volgende rollen kunnen sleutels weergeven en opnieuw genereren:

Eigenaar
Inzender
Inzender voor zoekservice
Beheerder en medebeheerder (klassiek)

De volgende rollen hebben geen toegang tot API-sleutels:

Lezer
Inzender voor zoekindexgegevens
Zoekindexgegevenslezer

Bestaande sleutels zoeken

U kunt API-sleutels weergeven en beheren in Azure Portal of via PowerShell, Azure CLI of REST API.

Meld u aan bij Azure Portal en zoek uw zoekservice.
Selecteer onder Instellingen sleutels om beheerders- en querysleutels weer te geven.

Installeer de Az.Search module:
```
Install-Module Az.Search
```

Beheerderssleutels retourneren:

Get-AzSearchAdminKeyPair -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Querysleutels retourneren:

Get-AzSearchQueryKey -ResourceGroupName <resource-group-name> -ServiceName <search-service-name>

Gebruik de volgende opdrachten om respectievelijk beheerders- en query-API-sleutels te retourneren:

az search admin-key show --resource-group <myresourcegroup> --service-name <myservice>

az search query-key list --resource-group <myresourcegroup> --service-name <myservice>

Gebruik lijstbeheerderssleutels of lijstquerysleutels in de REST API voor beheer om API-sleutels te retourneren.

U moet een geldige roltoewijzing hebben om API-sleutels te retourneren of bij te werken. Zie Uw Azure AI-Search-service beheren met REST API's voor hulp bij het voldoen aan rolvereisten met behulp van de REST API's.

POST https://management.azure.com/subscriptions/{{subscriptionId}}/resourceGroups/{{resource-group}}/providers//Microsoft.Search/searchServices/{{search-service-name}}/listAdminKeys?api-version=2023-11-01

Querysleutels maken

Querysleutels worden gebruikt voor alleen-lezentoegang tot documenten in een index voor bewerkingen die gericht zijn op een documentenverzameling. Zoek-, filter- en suggestiequery's zijn alle bewerkingen die een querysleutel gebruiken. Voor elke alleen-lezenbewerking die systeemgegevens- of objectdefinities retourneert, zoals een indexdefinitie of indexeerfunctiestatus, is een beheerderssleutel vereist.

Het beperken van de toegang en bewerkingen in client-apps is essentieel voor het beveiligen van de zoekassets op uw service. Gebruik altijd een querysleutel in plaats van een beheersleutel voor elke query die afkomstig is van een client-app.

Meld u aan bij Azure Portal en zoek uw zoekservice.
Selecteer onder Instellingen sleutels om API-sleutels weer te geven.
Gebruik onder Querysleutels beheren de querysleutel die al is gegenereerd voor uw service of maak nieuwe querysleutels. De standaardquerysleutel heeft geen naam, maar andere gegenereerde querysleutels kunnen worden benoemd voor beheerbaarheid.

Gebruik Querysleutels maken in de REST API voor beheer.

U moet een geldige roltoewijzing hebben om API-sleutels te maken of te beheren. Zie Uw Azure AI-Search-service beheren met REST API's voor hulp bij het voldoen aan rolvereisten met behulp van de REST API's.

POST https://management.azure.com/subscriptions/{subscriptionId}/resourceGroups/{resourceGroupName}/providers/Microsoft.Search/searchServices/{searchServiceName}/createQueryKey/{name}?api-version=2023-11-01

Beheerderssleutels opnieuw genereren

Er worden twee beheerderssleutels gemaakt voor elke service, zodat u een primaire sleutel kunt roteren terwijl u de secundaire sleutel gebruikt voor bedrijfscontinuïteit.

Selecteer Onder Instellingen de optie Sleutels en kopieer de secundaire sleutel.
Werk voor alle toepassingen de API-sleutelinstellingen bij om de secundaire sleutel te gebruiken.
Genereer de primaire sleutel opnieuw.
Werk alle toepassingen bij om de nieuwe primaire sleutel te gebruiken.

Als u per ongeluk beide sleutels tegelijk opnieuw genereert, mislukken alle clientaanvragen die deze sleutels gebruiken met HTTP 403 Verboden. Inhoud wordt echter niet verwijderd en u bent niet permanent vergrendeld.

U hebt nog steeds toegang tot de service via de portal of programmatisch. Beheerfuncties werken via een abonnements-id en geen service-API-sleutel en zijn dus nog steeds beschikbaar, zelfs als uw API-sleutels dat niet zijn.

Nadat u nieuwe sleutels hebt gemaakt via de portal of beheerlaag, wordt de toegang hersteld naar uw inhoud (indexen, indexeerfuncties, gegevensbronnen, synoniemenkaarten) zodra u deze sleutels opgeeft voor aanvragen.

Beveiligde API-sleutels

Gebruik roltoewijzingen om de toegang tot API-sleutels te beperken.

Het is niet mogelijk om door de klant beheerde sleutelversleuteling te gebruiken om API-sleutels te versleutelen. Alleen gevoelige gegevens in de zoekservice zelf (bijvoorbeeld indexinhoud of verbindingsreeks s in definities van gegevensbronobjecten) kunnen CMK-versleuteld zijn.

Navigeer naar de pagina van uw zoekservice in Azure Portal.
Selecteer in het linkernavigatiedeelvenster Toegangsbeheer (IAM) en selecteer vervolgens het tabblad Roltoewijzingen .
Selecteer in het rolfilter de rollen die gemachtigd zijn om sleutels weer te geven of te beheren (Eigenaar, Inzender, Inzender voor zoekservice). De resulterende beveiligingsprinciplen die aan deze rollen zijn toegewezen, hebben sleutelmachtigingen voor uw zoekservice.
Controleer als voorzorgsmaatregel ook het tabblad Klassieke beheerders om te bepalen of beheerders en medebeheerders toegang hebben.

Aanbevolen procedures

Gebruik alleen API-sleutels als openbaarmaking van gegevens geen risico is (bijvoorbeeld wanneer u voorbeeldgegevens gebruikt) en als u achter een firewall werkt. Blootstelling van API-sleutels is een risico voor zowel gegevens als onbevoegd gebruik van uw zoekservice.
Controleer altijd code, voorbeelden en trainingsmateriaal voordat u publiceert om ervoor te zorgen dat u geen geldige API-sleutels achterlaat.
Schakel voor productieworkloads over naar Microsoft Entra-id en op rollen gebaseerde toegang. Als u API-sleutels wilt blijven gebruiken, moet u ook altijd controleren wie toegang heeft tot uw API-sleutels en API-sleutels regelmatig opnieuw genereren.

Delen via