Delen via

.NET Aspire Azure AI Search-integratie

  • Artikel

Omvat: Hosting-integratie en Client-integratie

Met de integratie .NET AspireAzure AI Search-documenten kunt u vanuit uw Azure toepassingen verbinding maken met -services (voorheen Azure Cognitive Search). Azure AI Search is een systeem voor het ophalen van bedrijfsklare informatie voor uw heterogene inhoud die u opneemt in een zoekindex en die gebruikers via query's en apps kunt weergeven. Het wordt geleverd met een uitgebreide set geavanceerde zoektechnologieën, gebouwd voor hoogwaardige toepassingen op elke schaal.

Hostingintegratie

De modellen voor de hostingintegratie van .NET AspireAzure AI Search modelleren de Azure AI Search-resource als het type AzureSearchResource. Als u toegang wilt krijgen tot dit type en de API's om ze binnen uw app-host project uit te drukken, installeer dan het 📦Aspire.Hosting.Azure.Search NuGet-pakket:

dotnet add package Aspire.Hosting.Azure.Search

Zie dotnet pakket toevoegen of Pakketafhankelijkheden beheren in .NET toepassingenvoor meer informatie.

Een Azure AI Search-resource toevoegen

Als u een AzureSearchResource wilt toevoegen aan uw app-hostproject, roept u de AddAzureSearch methode aan die een naam oplevert:

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.AddAzureSearch("search");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

Met de voorgaande code wordt een Azure AI Search-resource met de naam search toegevoegd aan het app-hostproject. De methode WithReference geeft de verbindingsgegevens door aan het ExampleProject-project.

Belangrijk

Wanneer u AddAzureSearchaanroept, wordt impliciet AddAzureProvisioning(IDistributedApplicationBuilder)aangeroepen. Hiermee wordt ondersteuning toegevoegd voor het dynamisch genereren van Azure resources tijdens het opstarten van de app. De app moet het juiste abonnement en de juiste locatie configureren. Zie Lokaal inrichten voor meer informatie: Configuratie

Gegenereerde implementatie Bicep

Als je nieuw bent met Bicep, is dit een domeinspecifieke taal voor het definiëren van Azure-bronnen. Met .NET.NET Aspirehoeft u Bicep niet handmatig te schrijven; In plaats daarvan genereren de inrichtings-API's Bicep voor u. Wanneer u uw app publiceert, wordt de gegenereerde Bicep samen met het manifestbestand weergegeven. Wanneer u een Azure AI Search-resource toevoegt, wordt Bicep gegenereerd om de zoekservice met de juiste standaardinstellingen in te richten.

@description('The location for the resource(s) to be deployed.')
param location string = resourceGroup().location

param principalType string

param principalId string

resource search 'Microsoft.Search/searchServices@2023-11-01' = {
  name: take('search-${uniqueString(resourceGroup().id)}', 60)
  location: location
  properties: {
    hostingMode: 'default'
    disableLocalAuth: true
    partitionCount: 1
    replicaCount: 1
  }
  sku: {
    name: 'basic'
  }
  tags: {
    'aspire-resource-name': 'search'
  }
}

resource search_SearchIndexDataContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '8ebe5a00-799e-43f5-93ac-243d3dce84a7')
    principalType: principalType
  }
  scope: search
}

resource search_SearchServiceContributor 'Microsoft.Authorization/roleAssignments@2022-04-01' = {
  name: guid(search.id, principalId, subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0'))
  properties: {
    principalId: principalId
    roleDefinitionId: subscriptionResourceId('Microsoft.Authorization/roleDefinitions', '7ca78c08-252a-4471-8644-bb5ff32d4ba0')
    principalType: principalType
  }
  scope: search
}

output connectionString string = 'Endpoint=https://${search.name}.search.windows.net'

De voorgaande Bicep is een module die een Azure AI Search-serviceresource in richt met de volgende standaardwaarden:

  • location: de locatieparameter van de resourcegroep wordt standaard ingesteld op resourceGroup().location.
  • principalType: de principal-typeparameter van de Azure AI Search-resource.
  • principalId: de principal-id-parameter van de Azure AI Search-resource.
  • search: de resource die de Azure AI Search-service vertegenwoordigt.
    • properties: de eigenschappen van de Azure AI Search-service:
      • hostingMode: is ingesteld op default.
      • disableLocalAuth: is ingesteld op true.
      • partitionCount: is ingesteld op 1.
      • replicaCount: is ingesteld op 1.
    • sku: standaard ingesteld op basic.
  • search_SearchIndexDataContributor: de roltoewijzing voor de rol van gegevensbijdrager voor de AI Search-index. Voor meer informatie, zie Inzender voor zoekindexgegevens.
  • search_SearchServiceContributor: de roltoewijzing voor de rol van de Azure AI Search-servicebijdrager. Zie zoeksysteemmedewerkervoor meer informatie.
  • connectionString: de verbindingsreeks voor de Azure AI Search-service, die wordt gebruikt om verbinding te maken met de service. De verbindingsreeks wordt gegenereerd met behulp van de eigenschap Endpoint van de Azure AI Search-service.

De gegenereerde Bicep is een uitgangspunt en kan worden aangepast aan uw specifieke vereisten.

Voorzieningsinfrastructuur personaliseren

Alle .NET AspireAzure resources zijn subklassen van het AzureProvisioningResource type. Met dit type kunt u de gegenereerde Bicep aanpassen door een vloeiende API te bieden waarmee u de Azure-resources kunt configureren, met behulp van de ConfigureInfrastructure<T>(IResourceBuilder<T>, Action<AzureResourceInfrastructure>)-API. U kunt bijvoorbeeld de partities, replica's en meer van de zoekservice configureren:

builder.AddAzureSearch("search")
    .ConfigureInfrastructure(infra =>
    {
        var searchService = infra.GetProvisionableResources()
                                 .OfType<SearchService>()
                                 .Single();

        searchService.PartitionCount = 6;
        searchService.ReplicaCount = 3;
        searchService.SearchSkuName = SearchServiceSkuName.Standard3;
        searchService.Tags.Add("ExampleKey", "Example value");
    });

De voorgaande code:

Er zijn nog veel meer configuratieopties beschikbaar om de Azure AI Search-resource aan te passen. Zie Azure.Provisioning aanpassingvoor meer informatie.

Verbinding maken met een bestaande Azure AI Search-service

Mogelijk hebt u een bestaande Azure AI Search-service waarmee u verbinding wilt maken. U kunt een aanroep koppelen om aan te geven dat uw AzureSearchResource een bestaande resource is:

var builder = DistributedApplication.CreateBuilder(args);

var existingSearchName = builder.AddParameter("existingSearchName");
var existingSearchResourceGroup = builder.AddParameter("existingSearchResourceGroup");

var search = builder.AddAzureSearch("search")
                    .AsExisting(existingSearchName, existingSearchResourceGroup);

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

Zie Azurevoor meer informatie over hoe Azure AI Search-middelen worden behandeld als bestaande middelen.

Als alternatief voor het representeren van een Azure AI Search-resource, kunt u een verbindingsreeks toevoegen aan de app-host. Dit is een zwak getypte benadering die uitsluitend is gebaseerd op een string waarde. Als u een verbinding wilt toevoegen aan een bestaande Azure AI Search-service, roept u de methode AddConnectionString aan:

var builder = DistributedApplication.CreateBuilder(args);

var search = builder.ExecutionContext.IsPublishMode
    ? builder.AddAzureSearch("search")
    : builder.AddConnectionString("search");

builder.AddProject<Projects.ExampleProject>()
       .WithReference(search);

// After adding all resources, run the app...

Notitie

Verbindingsreeksen worden gebruikt om een breed scala aan verbindingsgegevens weer te geven, waaronder databaseverbindingen, berichtbrokers, eindpunt-URI's en andere services. In .NET.NET Aspire nomenclatuur wordt de term "verbindingsreeks" gebruikt om alle soorten verbindingsgegevens weer te geven.

De verbindingsreeks wordt geconfigureerd in de configuratie van de app-host, meestal onder Gebruikersgeheimen, onder de sectie ConnectionStrings:

{
  "ConnectionStrings": {
    "search": "https://{account_name}.search.azure.com/"
  }
}

Voor meer informatie, zie Bestaande Azure resources toevoegen met verbindingsreeksen.

Gezondheidscontroles van hostingintegratie

De integratie van AI Search-hosting Azure implementeert momenteel geen gezondheidscontroles. Deze beperking is onderhevig aan wijzigingen in toekomstige releases. Zoals altijd kunt u gerust een probleem openen als u suggesties of feedback hebt.

Client integratie

Om te beginnen met de .NET AspireAzure AI Search Documents-clientintegratie, installeer het .NET Aspire NuGet-pakket in het project dat de Azure AI Search Documents-client gebruikt, dat wil zeggen het project voor de toepassing die gebruikmaakt van deze client.

dotnet add package Aspire.Azure.Search.Documents

Een Azure AI Search-indexclient toevoegen

Roep in het Program.cs bestand van het clientgebruikte project de AddAzureSearchClient-extensiemethode aan op een IHostApplicationBuilder om een SearchIndexClient te registreren voor gebruik via de container voor afhankelijkheidsinjectie. De methode gebruikt een verbindingsnaamparameter.

builder.AddAzureSearchClient(connectionName: "search");

Hint

De parameter connectionName moet overeenkomen met de naam die wordt gebruikt bij het toevoegen van de Azure AI Search-resource in het app-hostproject. Zie Een Azure AI Search-resource toevoegenvoor meer informatie.

Nadat u de SearchIndexClienthebt toegevoegd, kunt u de clientinstantie ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld, om de clientinstantie van een voorbeeldservice op te halen:

public class ExampleService(SearchIndexClient indexClient)
{
    // Use indexClient
}

U kunt ook een SearchClient ophalen die kan worden gebruikt voor het uitvoeren van query's door de methode GetSearchClient(String) aan te roepen:

public class ExampleService(SearchIndexClient indexClient)
{
    public async Task<long> GetDocumentCountAsync(
        string indexName,
        CancellationToken cancellationToken)
    {
        var searchClient = indexClient.GetSearchClient(indexName);

        var documentCountResponse = await searchClient.GetDocumentCountAsync(
            cancellationToken);

        return documentCountResponse.Value;
    }
}

Zie voor meer informatie:

De gesleutelde AI-zoekindexclient Azure toevoegen

Er kunnen situaties zijn waarin u meerdere SearchIndexClient exemplaren met verschillende verbindingsnamen wilt registreren. Als u AI Search-clients met sleutel Azure wilt registreren, roept u de AddKeyedAzureSearchClient-methode aan.

builder.AddKeyedAzureSearchClient(name: "images");
builder.AddKeyedAzureSearchClient(name: "documents");

Belangrijk

Wanneer u sleutelservices gebruikt, wordt verwacht dat uw Azure AI Search-resource twee benoemde verbindingen heeft geconfigureerd, één voor de images en één voor de documents.

Vervolgens kunt u de clientexemplaren ophalen met behulp van afhankelijkheidsinjectie. Bijvoorbeeld om de clients op te halen uit een service:

public class ExampleService(
    [KeyedService("images")] SearchIndexClient imagesClient,
    [KeyedService("documents")] SearchIndexClient documentsClient)
{
    // Use clients...
}

Zie Keyed-services in .NETvoor meer informatie.

Configuratie

De bibliotheek .NET AspireAzure AI Search-documenten biedt meerdere opties voor het configureren van de Azure AI Search-verbinding op basis van de vereisten en conventies van uw project. Er moet een Endpoint of een ConnectionString worden opgegeven.

Een verbindingsreeks gebruiken

Er kan een verbinding worden gemaakt vanaf het tabblad Sleutels en Eindpunt met het formaat Endpoint={endpoint};Key={key};. U kunt de naam van de verbindingsreeks opgeven bij het aanroepen van builder.AddAzureSearchClient():

builder.AddAzureSearchClient("searchConnectionName");

De verbindingsreeks wordt opgehaald uit de sectie ConnectionStrings configuratie. Er worden twee verbindingsindelingen ondersteund:

Accounteindpunt

De aanbevolen methode is om een Endpointte gebruiken, die werkt met de eigenschap AzureSearchSettings.Credential om een verbinding tot stand te brengen. Als er geen inloggegevens zijn geconfigureerd, wordt de DefaultAzureCredential gebruikt.

{
  "ConnectionStrings": {
    "search": "https://{search_service}.search.windows.net/"
  }
}
Verbindingsreeks

U kunt ook een verbindingsreeks met sleutel gebruiken. dit is niet de aanbevolen methode:

{
  "ConnectionStrings": {
    "search": "Endpoint=https://{search_service}.search.windows.net/;Key={account_key};"
  }
}

Configuratieproviders gebruiken

De .NET AspireAzure AI Search-bibliotheek ondersteunt Microsoft.Extensions.Configuration. Hiermee worden de AzureSearchSettings en SearchClientOptions vanuit de configuratie geladen met behulp van de Aspire:Azure:Search:Documents-sleutel. Voorbeeld appsettings.json waarmee een aantal van de opties wordt geconfigureerd:

{
  "Aspire": {
    "Azure": {
      "Search": {
        "Documents": {
          "DisableTracing": false
        }
      }
    }
  }
}

Zie voor het volledige AI Search Documents-clientintegratieschema .Search.Documents/ConfigurationSchema.json.

Gebruik inline-delegaten

U kunt ook de Action<AzureSearchSettings> configureSettings delegate doorgeven om bepaalde of alle opties inline in te stellen, bijvoorbeeld om tracering vanuit de code uit te schakelen.

builder.AddAzureSearchClient(
    "searchConnectionName",
    static settings => settings.DisableTracing = true);

U kunt de SearchClientOptions ook instellen met behulp van de optionele parameter Action<IAzureClientBuilder<SearchIndexClient, SearchClientOptions>> configureClientBuilder van de methode AddAzureSearchClient. Als u bijvoorbeeld de client-id voor deze client wilt instellen:

builder.AddAzureSearchClient(
    "searchConnectionName",
    configureClientBuilder: builder => builder.ConfigureOptions(
        static options => options.Diagnostics.ApplicationId = "CLIENT_ID"));

Gezondheidscontroles voor Client integratie

.NET .NET Aspire clientintegraties hebben standaard gezondheidscontroles ingeschakeld voor alle diensten. Evenzo, schakelen veel .NET.NET Aspirehostingintegraties ook eindpunten voor gezondheidscontrole in. Zie voor meer informatie:

De integratie van .NET AspireAzure AI Search Documents implementeert een enkele gezondheidscontrole die de GetServiceStatisticsAsync-methode aanroept op de SearchIndexClient om te verifiëren dat de service beschikbaar is.

Waarneembaarheid en telemetrie

.NET .NET Aspire integraties stellen automatisch logging-, tracing- en metricsconfiguraties in, die ook wel bekendstaan als de pijlers van zichtbaarheid. Zie .NET.NET Aspire overzicht van integratieintegratiesvoor meer informatie over de waarneembaarheid en telemetrie van integraties. Afhankelijk van de back-upservice ondersteunen sommige integraties mogelijk slechts enkele van deze functies. Sommige integraties ondersteunen bijvoorbeeld logboekregistratie en tracering, maar geen metrische gegevens. Telemetriefuncties kunnen ook worden uitgeschakeld met behulp van de technieken die worden weergegeven in de sectie Configuratie.

Loggen

De integratie .NET AspireAzure AI Search Documents maakt gebruik van de volgende logboekcategorieën:

  • Azure
  • Azure.Core
  • Azure.Identity

Opsporing

De AI Search Documents-integratie .NET AspireAzure verzendt traceringsactiviteiten met behulp van OpenTelemetry wanneer er interactie is met de zoekdienst.

Zie ook