Verbinden eines Suchdiensts für andere Azure-Ressourcen mithilfe einer verwalteten Identität

Artikel
04/11/2024

Sie können eine Verbindung des Azure KI Search-Diensts mit anderen Azure-Ressourcen konfigurieren, indem Sie eine systemseitig oder benutzerseitig zugewiesene verwaltete Identität und eine Azure-Rollenzuweisung verwenden. Verwaltete Identitäten und Rollenzuweisungen machen die Übergabe von Geheimnissen und Anmeldeinformationen in einer Verbindungszeichenfolge oder Code überflüssig.

Voraussetzungen

Ein Suchdienst im Basic-Tarif oder höher.
Eine Azure-Ressource, die eingehende Anforderungen von einer Microsoft Entra-Anmeldung mit einer gültigen Rollenzuweisung akzeptiert.

Unterstützte Szenarios

Azure KI Search kann eine system- oder benutzerseitig zugewiesene verwaltete Identität für ausgehende Verbindungen mit Azure-Ressourcen verwenden. Eine systemseitig verwaltete Identität wird angegeben, wenn eine Verbindungszeichenfolge die eindeutige Ressourcen-ID eines Microsoft Entra ID-fähigen Diensts oder einer Microsoft Entra ID-fähigen Anwendung ist. Eine vom Benutzer zugewiesene verwaltete Identität wird mithilfe einer Eigenschaft „identity“ angegeben.

Ein Suchdienst verwendet Azure Storage als Datenquelle für den Indexer und als Datensenke für Debugsitzungen, die Anreicherungsspeicherung und den Wissensspeicher. Für Suchfeatures, die in den Speicher zurückschreiben, benötigt die verwaltete Identität die Zuweisung einer „Mitwirkender“-Rolle, wie im Abschnitt Zuweisen einer Rolle beschrieben.

Szenario	Systemseitig verwaltete Identität	Benutzerseitig zugewiesene verwaltete Identität (Vorschau)
Indexerverbindungen mit unterstützten Azure-Datenquellen^1,³	Ja	Ja
Azure Key Vault für kundenseitig verwalteten Schlüssel	Ja	Ja
Debugsitzungen (in Azure Storage gehostet)¹	Ja	Nein
Anreicherungscache (in Azure Storage gehostet)^1,²	Ja	Ja
Knowledge Store (in Azure Storage gehostet)¹	Ja	Ja
Benutzerdefinierte Qualifikationen (in Azure Functions oder gleichwertig gehostet)	Ja	Ja
Azure OpenAI Einbettungsskill	Ja	Ja
Azure OpenAI-Vektorisierung	Ja	Ja

¹ Für die Konnektivität zwischen Suche und Speicher legt Ihre Netzwerksicherheitskonfiguration Einschränkungen fest, welche Art von verwalteter Identität Sie verwenden können. Nur eine systemseitig verwaltete Identität kann für eine Verbindung mit Speicher in derselben Region über die Ausnahme für vertrauenswürdige Dienste oder die Ressourceninstanzregel verwendet werden. Ausführliche Informationen finden Sie unter Zugriff auf ein netzwerkgeschütztes Speicherkonto.

² Eine Methode zum Angeben eines Anreicherungscaches befindet sich im Assistenten zum Importieren von Daten. Derzeit akzeptiert der Assistent keine verwaltete Identitätsverbindungszeichenfolge für den Anreicherungscache. Nach Abschluss des Assistenten können Sie jedoch die Verbindungszeichenfolge in der JSON-Definition des Indexers aktualisieren, und entweder eine systemseitig oder eine benutzerseitig zugewiesene verwaltete Identität angeben und anschließend den Indexer erneut ausführen.

³ Beachten Sie, dass das Deaktivieren von Schlüsseln im Azure-Speicherkonto derzeit für die Azure-Tabelle, die als Datenquelle verwendet wird, nicht unterstützt wird. Obwohl die verwaltete Identität verwendet wird, um die Speicherschlüssel nicht explizit bereitzustellen, verwendet der KI-Suchdienst die Schlüssel dennoch für diese Implementierung.

Erstellen einer vom System verwalteten Identität

Wenn eine systemseitig zugewiesene verwaltete Identität aktiviert ist, wird in Azure eine Identität für den Suchdienst erstellt, die für die Authentifizierung bei anderen Azure-Diensten innerhalb desselben Mandanten und desselben Abonnements verwendet werden kann. Anschließend können Sie diese Identität in Azure RBAC-Zuweisungen (rollenbasierte Zugriffssteuerung) verwenden, die den Zugriff auf Daten während der Indizierung ermöglichen.

Eine vom System zugewiesene verwaltete Identität ist für Ihren Suchdienst eindeutig und für ihre Lebensdauer an den Dienst gebunden.

Melden Sie sich beim Azure-Portal an, und finden Sie Ihren Suchdienst.
Wählen Sie unter EinstellungenIdentität aus:
Wählen Sie auf der Registerkarte Systemseitig zugewiesen unter Status die Option Ein aus.
Wählen Sie Speichern.

Nach dem Speichern wird ein Objektbezeichner angezeigt, der Ihrem Suchdienst zugewiesen wurde.

Weitere Informationen finden Sie unter Erstellen oder Aktualisieren des Diensts (Verwaltungs-REST-API).

Sie können die Verwaltungs-REST-API anstelle des Portals verwenden, um eine benutzerseitig zugewiesene verwaltete Identität zuzuweisen.

Formulieren Sie eine Anforderung zum Erstellen oder Aktualisieren eines Suchdiensts.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2023-11-01
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "SystemAssigned"
  }
}

Die Bestätigung und ein Objektbezeichner für die vom System verwaltete Identität werden in der Antwort zurückgegeben.

Erstellen einer benutzerseitig zugewiesenen verwalteten Identität (Vorschau)

Eine benutzerseitig verwaltete Identität ist eine Azure-Ressource. Dies ist hilfreich, wenn Sie mehr Granularität bei Rollenzuweisungen benötigen, da Sie separate Identitäten für verschiedene Anwendungen und Szenarien erstellen können.

Wichtig

Dieses Feature befindet sich in der öffentlichen Vorschau und unterliegt den zusätzlichen Nutzungsbedingungen. Benutzerseitig zugewiesene verwaltete Identitäten werden derzeit für Verbindungen mit einem netzwerkgeschützten Speicherkonto nicht unterstützt. Die Suchanforderung erfordert derzeit eine öffentliche IP-Adresse.

Azure portal
REST-API

Melden Sie sich beim Azure-Portal
Wählen Sie + Ressource erstellen.
Suchen Sie in der Suchleiste „Dienste und Marketplace durchsuchen“ nach „Benutzerseitig zugewiesene verwaltete Identität“, und wählen Sie dann Erstellen aus.
Wählen Sie das Abonnement, die Ressourcengruppe und die Region an. Geben Sie einen beschreibenden Namen für die Identität ein.
Wählen Sie Erstellen aus, und warten Sie, bis die Bereitstellung der Ressource abgeschlossen ist.

In den nächsten Schritten weisen Sie Ihrem Suchdienst die benutzerseitig zugewiesene verwaltete Identität zu.
Wählen Sie auf ihrer Suchdienstseite unter EinstellungenIdentität aus.
Wählen Sie auf der Registerkarte Benutzerseitig zugewiesen die Option Hinzufügen aus.
Wählen Sie das Abonnement und dann die vom Benutzer zugewiesene verwaltete Ressource aus, die Sie im vorherigen Schritt erstellt haben.

Sie können die Verwaltungs-REST-API anstelle des Portals verwenden, um eine benutzerseitig zugewiesene verwaltete Identität zuzuweisen. Achten Sie darauf, die Version 2021-04-01-Preview für diese Aufgabe zu verwenden.

Formulieren Sie eine Anforderung zum Erstellen oder Aktualisieren eines Suchdiensts.

PUT https://management.azure.com/subscriptions/subid/resourceGroups/rg1/providers/Microsoft.Search/searchServices/mysearchservice?api-version=2021-04-01-preview
{
  "location": "[region]",
  "sku": {
    "name": "[sku]"
  },
  "properties": {
    "replicaCount": [replica count],
    "partitionCount": [partition count],
    "hostingMode": "default"
  },
  "identity": {
    "type": "UserAssigned",
    "userAssignedIdentities": {
      "/subscriptions/[subscription ID]/resourcegroups/[resource group name]/providers/Microsoft.ManagedIdentity/userAssignedIdentities/[name of managed identity]": {}
    }
  }
}

Legen Sie die Eigenschaft „identity“ fest, um eine vollqualifizierte verwaltete Identität anzugeben:
- „type“ ist der Typ der Identität. Gültige Werte sind „SystemAssigned“, „UserAssigned“ oder „SystemAssigned, UserAssigned“ für beide. Der Wert „None“ löscht alle zuvor zugewiesenen Identitäten aus dem Suchdienst.
- „userAssignedIdentities“ enthält die Details der benutzerseitig zugewiesenen verwalteten Identität. Diese Identität muss bereits vorhanden sein, damit Sie sie in der Anforderung „Dienst erstellen oder aktualisieren“ angeben können.

Zulassen des Firewallzugriffs

Wenn sich Ihre Azure-Ressource hinter einer Firewall befindet, achten Sie darauf, dass eine Eingangsregel vorhanden ist, die Anforderungen von Ihrem Suchdienst zulässt.

Verwenden Sie für Verbindungen in derselben Region mit Azure Blob Storage oder Azure Data Lake Storage Gen2 eine systemseitig zugewiesene verwaltete Identität und die Ausnahme für vertrauenswürdige Dienste. Optional können Sie eine Ressourceninstanzregel konfigurieren, um Anforderungen zuzulassen.
Konfigurieren Sie für alle anderen Ressourcen und Verbindungen eine IP-Firewallregel, die Anforderungen von Search zulässt. Weitere Informationen dazu finden Sie unter Indexerzugriff auf mit Azure-Netzwerksicherheitsfeatures geschützten Inhalt.

Zuweisen einer Rolle

Eine verwaltete Identität muss mit einer Azure-Rolle gekoppelt werden, die Berechtigungen für die Azure-Ressource bestimmt.

Datenleseberechtigungen sind für Indexerdatenverbindungen und für den Zugriff auf einen vom Kunden verwalteten Schlüssel in Azure Key Vault erforderlich.
Berechtigungen für Mitwirkende (Schreibberechtigungen) sind für KI-Anreicherungsfeatures erforderlich, die Azure Storage zum Hosten von Debugsitzungsdaten, Zwischenspeichern von Anreicherungen und langfristige Inhaltsspeicherung in einem Wissensspeicher verwenden.

Die folgenden Schritte gelten für Azure Storage. Wenn es sich bei Ihrer Ressource um Azure Cosmos DB oder Azure SQL handelt, sind die Schritte ähnlich.

Melden Sie sich beim Azure-Portal an und suchen Sie Ihre Azure-Ressource, auf die der Suchdienst Zugriff haben muss.
Wählen Sie in Azure Storage im linken Navigationsbereich Zugriffssteuerung (AIM) aus.
Wählen Sie Rollenzuweisung hinzufügen aus.

Wählen Sie auf der Seite Rolle die für Ihren Suchdienst erforderlichen Rollen aus:

Aufgabe	Rollenzuweisung
Blob-Indizierung mit einem Indexer	Fügen Sie Leser von Speicher-Blobdaten hinzu
ADLS Gen2-Indizierung mit einem Indexer	Fügen Sie Leser von Speicher-Blobdaten hinzu
Tabellenindizierung mithilfe eines Indexers	Gewähren Sie Lese- und Datenzugriff
Dateiindizierung mit einem Indexer	Gewähren Sie Lese- und Datenzugriff
Schreiben in einen Wissensspeicher	Fügen Sie Mitwirkender an Speicher-Blobdaten für Objekt- und Dateiprojektionen sowie Lese- und Datenzugriff für Tabellenprojektionen hinzu.
Schreiben in einen Anreicherungscache	Fügen Sie Mitwirkender an Speicher-Blobdaten hinzu
Debugsitzungsstatus speichern	Fügen Sie Mitwirkender an Speicher-Blobdaten hinzu
Einbetten von Daten (Vektorisierung) mithilfe von Azure OpenAI-Einbettungsmodellen	Cognitive Services OpenAI-Benutzer hinzufügen

Wählen Sie auf der Seite Mitglieder die Option Verwaltete Identität aus.
Wählen Sie Mitglieder aus. Wählen Sie auf der Seite Verwaltete Identität auswählen Ihr Abonnement aus, filtern Sie nach Diensttyp, und wählen Sie dann den Dienst aus. Nur die Dienste, die über eine verwaltete Identität verfügen, können ausgewählt werden.
Wählen Sie Überprüfen und zuweisen aus.

Beispiele für Verbindungszeichenfolgen

Sobald eine verwaltete Identität für den Suchdienst definiert und eine Rollenzuweisung erteilt wurde, können ausgehende Verbindungen geändert werden, um die eindeutige Ressourcen-ID der anderen Azure-Ressource zu verwenden. Hier sehen Sie einige Beispiele für Verbindungszeichenfolgen für verschiedene Szenarien.

Blobdatenquelle (System):

Eine Indexerdatenquelle enthält eine „Credentials“-Eigenschaft, die bestimmt, wie die Verbindung mit der Datenquelle hergestellt wird. Das folgende Beispiel zeigt eine Verbindungszeichenfolge, die die eindeutige Ressourcen-ID eines Speicherkontos angibt. Microsoft Entra ID authentifiziert die Anforderung mithilfe der systemseitig verwalteten Identität des Suchdiensts. Beachten Sie, dass die Verbindungszeichenfolge keinen Container beinhaltet. In einer Datenquellendefinition wird ein Containername in der Eigenschaft „container“ (nicht dargestellt) angegeben statt in der Verbindungszeichenfolge.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    }

Blob-Datenquelle (Benutzer):

Eine Suchanforderung an Azure Storage kann auch unter einer benutzerseitig zugewiesenen verwalteten Identität vorgenommen werden (derzeit in der Vorschauphase). Die Benutzeridentität des Suchdiensts wird in der Eigenschaft „identity“ angegeben. Sie können die Identität entweder über das Portal oder die REST-API-Vorschauversion 2021-04-30-Preview festlegen.

"credentials": {
    "connectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
    },
  . . .
"identity": {
    "@odata.type": "#Microsoft.Azure.Search.DataUserAssignedIdentity",
    "userAssignedIdentity": "/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.ManagedIdentity/userAssignedIdentities/{user-assigned-managed-identity-name}"
  }

Wissensspeicher:

Eine Wissensspeicherdefinition beinhaltet eine Verbindungszeichenfolge zum Azure Storage. In Azure Storage erstellt ein Wissensspeicher Projektionen in Form von Blobs und Tabellen. Die Verbindungszeichenfolge ist die eindeutige Ressourcen-ID Ihres Speicherkontos. Beachten Sie, dass die Zeichenfolge keine Container oder Tabellen im Pfad enthält. Diese werden in der eingebetteten Projektionsdefinition definiert, nicht in der Verbindungszeichenfolge.

"knowledgeStore": {
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/storage-account-name};"
}

Anreicherungscache:

Ein Indexer erstellt, verwendet und speichert den Container, der für die zwischengespeicherten Anreicherungen verwendet wird. Es ist nicht erforderlich, den Container in die Cacheverbindungszeichenfolge einzufügen. Sie finden die Objekt-ID im Portal auf der Seite Identität Ihres Suchdiensts.

"cache": {
  "enableReprocessing": true,
  "storageConnectionString": "ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name};"
}

Debugsitzung:

Eine Debugsitzung wird im Portal ausgeführt und nimmt eine Verbindungszeichenfolge an, wenn Sie die Sitzung starten. Sie können eine Verbindungszeichenfolge wie im folgenden Beispiel einfügen:

"ResourceId=/subscriptions/{subscription-ID}/resourceGroups/{resource-group-name}/providers/Microsoft.Storage/storageAccounts/{storage-account-name}/{container-name};",

Benutzerdefinierter Skill:

Ein benutzerdefinierter Skill ist auf den Endpunkt einer Azure-Funktion oder -App ausgerichtet, die benutzerdefinierten Code hostet. Der Endpunkt wird in der Definition des benutzerdefinierten Skills angegeben. Die Angabe von „authResourceId“ weist den Suchdienst an, eine Verbindung mithilfe einer verwalteten Identität herzustellen. Dabei wird die Anwendungs-ID der Zielfunktion oder -App in der Eigenschaft übergeben.

{
  "@odata.type": "#Microsoft.Skills.Custom.WebApiSkill",
  "description": "A custom skill that can identify positions of different phrases in the source text",
  "uri": "https://contoso.count-things.com",
  "authResourceId": "<Azure-AD-registered-application-ID>",
  "batchSize": 4,
  "context": "/document",
  "inputs": [ ... ],
  "outputs": [ ...]
}

Azure OpenAI-Einbettungsskill und Azure OpenAI-Vektorisierung:

Ein Azure OpenAI-Einbettungsskill und -Vektorisierung in der KI-Suche zielen auf den Endpunkt eines Azure OpenAI-Dienstes, der ein Einbettungsmodell hostet. Der Endpunkt wird in der Azure OpenAI-Einbettungsskilldefinition und/oder in der Azure OpenAI-Vektorisierungsdefinition angegeben. Die vom System verwaltete Identität wird verwendet, wenn sie konfiguriert ist und wenn die Felder „apikey“ und „authIdentity“ leer sind. Die Eigenschaft „authIdentity“ wird nur für die dem Benutzer zugewiesene verwaltete Identität verwendet.

{
  "@odata.type": "#Microsoft.Skills.Text.AzureOpenAIEmbeddingSkill",
  "description": "Connects a deployed embedding model.",
  "resourceUri": "https://url.openai.azure.com/",
  "deploymentId": "text-embedding-ada-002",
  "inputs": [
    {
      "name": "text",
      "source": "/document/content"
    }
  ],
  "outputs": [
    {
      "name": "embedding"
    }
  ]
}

 "vectorizers": [
    {
      "name": "my_azure_open_ai_vectorizer",
      "kind": "azureOpenAI",
      "azureOpenAIParameters": {
        "resourceUri": "https://url.openai.azure.com",
        "deploymentId": "text-embedding-ada-002"
      }
    }
  ]