Tutorial: Abfragen eines Azure KI Search-Indexes über Power Apps

2025-04-30

Nutzen Sie die Umgebung für die schnelle Anwendungsentwicklung von Power Apps, um eine benutzerdefinierte App für Ihre durchsuchbaren Inhalte in Azure KI Search zu erstellen.

In diesem Tutorial lernen Sie Folgendes:

Herstellen einer Verbindung mit Azure KI Search
Einrichten einer Abfrageanforderung
Visualisieren der Ergebnisse in einer Canvas-App

Sollten Sie über kein Azure-Abonnement verfügen, können Sie ein kostenloses Konto erstellen, bevor Sie beginnen.

Voraussetzungen

Power Apps-Konto mit einer Premium-Lizenz, z. B. einem Plan mit Power Apps pro App oder mit Power Apps pro Benutzer/Benutzerin.
Im Suchdienst gehosteter Index „hotels-sample“
Abfrage-API-Schlüssel

Schritt 1: Erstellen eines benutzerdefinierten Connectors

Ein Connector in Power Apps ist eine Verbindung zu einer Datenquelle. In diesem Schritt erstellen Sie einen benutzerdefinierten Connector, um eine Verbindung mit einem Suchindex in der Cloud herzustellen.

Führen Sie die Anmeldung bei Power Apps durch.
Auf der linken Seite, wählen Sie Benutzerdefinierte Steckverbinder aus.
Wählen Sie + Neuer benutzerdefinierter Connector und dann Aus leerer Vorlage erstellen aus.
Geben Sie einen Namen für Ihren benutzerdefinierten Connector ein (z. B. AzureSearchQuery), und wählen Sie dann Weiter aus.
Geben Sie Informationen auf der Seite „Allgemein“ ein:
- Symbolhintergrundfarbe (z. B. #007ee5)
- Beschreibung (z. B. „Connector für Azure KI Search“)
- Geben Sie unter „Host“ die URL Ihres Suchdiensts ein (z. B. <yourservicename>.search.windows.net).
- Geben Sie „/“ als Basis-URL ein.
Legen Sie auf der Seite „Sicherheit“ den Authentifizierungstyp auf API-Schlüssel und „Parameterbezeichnung“ sowie „Parametername“ auf api-key fest. Wählen Sie unter Parameterspeicherortdie Option Header aus, wie im folgenden Screenshot gezeigt.
Wählen Sie auf der Seite „Definitionen“ die Option + Neue Aktion aus, um eine Aktion zu erstellen, die den Index abfragt. Geben Sie für die Zusammenfassung und den Namen der Vorgangs-ID den Wert „Abfrage“ ein. Geben Sie als Beschreibung z. B. „Fragt den Suchindex ab“ ein.
Scrollen Sie nach unten. Klicken Sie unter „Anforderungen“ auf die Schaltfläche + Aus Beispiel importieren, um eine Abfrageanforderung an Ihren Suchdienst zu konfigurieren:
- Wählen Sie das Verb GET aus.
- Geben Sie unter „URL“ eine Beispielabfrage für Ihren Suchindex ein (search=* gibt alle Dokumente zurück, $select= ermöglicht die Auswahl von Feldern). Die API-Version muss angegeben werden. Vollständig angegeben, könnte eine URL wie im folgenden Beispiel aussehen. Beachten Sie, dass das https:// Präfix weggelassen wird.
```
mydemo.search.windows.net/indexes/hotels-sample-index/docs?search=*&$select=HotelName,Description,Address/City&api-version=2024-07-01
```
- Geben Sie bei „Headers“ Content-Type application/json ein.
  
  Power Apps nutzt die Syntax in der URL, um Parameter aus der Abfrage zu extrahieren: Die Parameter „search“, „select“ und „api-version“ können beim Durchlaufen des Assistenten konfiguriert werden.
Wählen Sie Importieren aus, um die Anforderung automatisch auszufüllen. Klicken Sie neben den einzelnen Parametern auf das Symbol ... , um die Parametermetadaten abschließend festzulegen. Wählen Sie nach jeder Parameteraktualisierung Zurück aus, um zur Seite „Anforderung“ zurückzukehren.
Für search: Legen Sie * als Standardwert fest, wählen Sie unter Erforderlich die Option Nein aus und unter Sichtbarkeit die Option Keine.
Für select: Legen Sie HotelName,Description,Address/City als Standardwert fest, wählen Sie unter Erforderlich die Option Nein aus und unter Sichtbarkeit die Option Keine.
Für api-version: Legen Sie 2024-07-01 als Standardwert fest, wählen Sie unter Erforderlich die Option Ja aus und unter Sichtbarkeit die Option Intern.
Für Content-Type: Legen Sie diese Option auf application/json fest.

Nachdem Sie diese Änderungen vorgenommen haben, wechseln Sie zur Ansicht Swagger-Editor. Im Abschnitt „parameters“ wird die folgende Konfiguration angezeigt:

parameters:
  - {name: search, in: query, required: false, type: string, default: '*'}
  - {name: $select, in: query, required: false, type: string, default: 'HotelName,Description,Address/City'}
  - {name: api-version, in: query, required: true, type: string, default: '2024-07-01',
    x-ms-visibility: internal}
  - {name: Content-Type, in: header, required: false, type: string}

Wechseln Sie zurück zum Assistenten und zu Schritt 3. Definition. Scrollen Sie nach unten zum Abschnitt „Antwort“. Wählen Sie Standardantwort hinzufügen aus. Dieser Schritt ist wichtig, da Power Apps dadurch das Schema der Antwort verstehen kann.

Fügen Sie eine Beispielantwort ein. Eine einfache Möglichkeit zum Erfassen einer Beispielantwort ist die Verwendung des Suchexplorers im Azure-Portal. Geben Sie im Suchexplorer die gleiche Abfrage wie für die Anforderung ein, fügen Sie jedoch $top=2 hinzu, um die Ergebnisse auf zwei Dokumente zu beschränken: search=*&$select=HotelName,Description,Address/City&$top=2.

Power Apps benötigt nur einige wenige Ergebnisse, um das Schema zu erkennen. Sie können die folgende Antwort nun in den Assistenten kopieren, vorausgesetzt, Sie verwenden „hotels-sample-index“.

{
    "@odata.context": "https://mydemo.search.windows.net/indexes('hotels-sample-index')/$metadata#docs(*)",
    "value": [
        {
            "@search.score": 1,
            "HotelName": "Happy Lake Resort & Restaurant",
            "Description": "The largest year-round resort in the area offering more of everything for your vacation – at the best value!  What can you enjoy while at the resort, aside from the mile-long sandy beaches of the lake? Check out our activities sure to excite both young and young-at-heart guests. We have it all, including being named “Property of the Year” and a “Top Ten Resort” by top publications.",
            "Address": {
                "City": "Seattle"
            }
        },
        {
            "@search.score": 1,
            "HotelName": "Grand Gaming Resort",
            "Description": "The Best Gaming Resort in the area.  With elegant rooms & suites, pool, cabanas, spa, brewery & world-class gaming.  This is the best place to play, stay & dine.",
            "Address": {
                "City": "Albuquerque"
            }
        }
    ]
}

Tipp

Es gibt ein Zeichenlimit für die JSON-Antwort, die Sie eingeben können, sodass Sie den JSON-Code vereinfachen möchten, bevor Sie ihn einfügen. Das Schema und das Format der Antwort sind wichtiger als die Werte selbst. Beispielsweise könnte der Text für das Beschreibungsfeld auf den ersten Satz beschränkt werden.

Wählen Sie Importieren aus, um die Standardantwort hinzuzufügen.
Wählen Sie rechts oben Connector erstellen aus, um die Definition zu speichern.
Wählen Sie Schließen aus, um den Connector zu schließen.

Schritt 2: Testen der Verbindung

Nach der erstmaligen Erstellung müssen Sie den Connector erneut über die Liste „Benutzerdefinierte Connectors“ öffnen, um ihn zu testen. Wenn Sie später weitere Änderungen vornehmen, können Sie die Tests im Assistenten durchführen.

Stellen Sie einen Abfrage-API-Schlüssel für diese Aufgabe bereit. Bei jeder Verbindungserstellung – ganz gleich, ob für einen Testlauf oder zur Einbindung in eine App – benötigt der Connector den zum Herstellen der Verbindung mit Azure KI Search verwendeten Abfrage-API-Schlüssel.

Wählen Sie ganz links Benutzerdefinierte Connectors aus.
Suchen Sie in der Liste nach dem Connector (in diesem Tutorial ist es „AzureSearchQuery“).
Wählen Sie den Connector aus, erweitern Sie die Liste mit den Aktionen, und wählen Sie Eigenschaften anzeigen aus.
Wählen Sie in der Dropdownliste der Vorgänge "6" aus. Testen.
Wählen Sie unter Vorgang testen die Option + Neue Verbindung aus.
Geben Sie einen Abfrage-API-Schlüssel ein. Dies ist eine Azure KI Search-Abfrage für den schreibgeschützten Zugriff auf einen Index. Sie können im Azure-Portal nach dem Schlüssel suchen.
Wählen Sie unter „Vorgänge“ die Schaltfläche Vorgang testen aus. Wenn der Vorgang erfolgreich ausgeführt wurde, sollte der Status 200 angezeigt werden, und im Text der Antwort sollte JSON-Code zu sehen sein, der die Suchergebnisse beschreibt.

Wenn der Test zu Fehlern führt, überprüfen Sie die Eingaben noch einmal. Überprüfen Sie insbesondere die Beispielantwort, und stellen Sie sicher, dass sie ordnungsgemäß erstellt wurde. Die Connectordefinition sollte die erwarteten Elemente für die Antwort enthalten.

Wenn Sie durch einen DLP-Richtlinienfehler (Data Loss Prevention, Verhinderung von Datenverlust) blockiert werden, lesen Sie die Fehlermeldung, um Anleitungen zu erhalten. Möglicherweise können Sie die Richtlinie ändern oder ihren Connector nicht blockierbar machen.

Schritt 3: Visualisieren der Ergebnisse

In diesem Schritt erstellen Sie eine Power App mit einem Suchfeld, einer Suchschaltfläche und einem Anzeigebereich für die Ergebnisse. Die Power App stellt eine Verbindung mit dem zuvor erstellten benutzerdefinierten Connector her, um die Daten aus Azure Search abzurufen.

Erweitern Sie auf der linken Seite Apps>Neue App>Mit Seitenentwurf beginnen.
Wählen Sie einen leeren Zeichenbereich mit dem Telefonlayout aus. Benennen Sie die App z. B. mit „Hotelfinder“. Wählen Sie Erstellen aus. Power Apps Studio wird angezeigt.
Wählen Sie in Studio die Registerkarte Daten und anschließend Daten hinzufügen aus. Suchen Sie dann nach dem neuen Connector, den Sie gerade erstellt haben. In diesem Tutorial heißt er AzureSearchQuery. Wählen Sie Verbindung hinzufügen aus.

Geben Sie den Abfrage-API-Schlüssel ein.

AzureSearchQuery ist nun eine Datenquelle, die für die Verwendung in Ihrer Anwendung verfügbar ist.
Fügen Sie der Canvas auf der Registerkarte Einfügen einige Steuerelemente hinzu.
Fügen Sie die folgenden Elemente ein:
- Ein Textfeld mit der Bezeichnung „Abfrage:“
- „Texteingabe“ (benennen Sie sie mit txtQuery, Standardwert: „*“)
- Eine Schaltfläche mit dem Text „Suchen“
- Ein vertikaler Katalog, genannt galleryResults
Die Canvas sollte in etwa wie folgt aussehen:
Damit die Schaltfläche „Suchen“ eine Abfrage sendet, fügen Sie die folgende Aktion in OnSelect ein:
```
If(!IsBlank(txtQuery.Text),
    ClearCollect(azResult, AzureSearchQuery.Query({search: txtQuery.Text}).value))
```
Der folgende Screenshot zeigt die Formelleiste für die OnSelect-Aktion.

Diese Aktion bewirkt, dass die Schaltfläche eine neue Sammlung mit dem Namen azResult mit dem Ergebnis der Suchabfrage aktualisiert. Dabei wird der Text im Textfeld txtQuery als Abfragebegriff verwendet.
Hinweis

Versuchen Sie Folgendes, wenn Sie einen Formelsyntaxfehler mit dem Hinweis erhalten, dass die ClearCollect-Funktion einige ungültige Funktionen aufweist:
- Stellen Sie zunächst sicher, dass der Connectorverweis korrekt ist. Löschen Sie den Namen des Connectors, und beginnen Sie, den Namen Ihres Connectors einzugeben. IntelliSense sollte den richtigen Connector und das richtige Verb vorschlagen.
- Falls der Fehler weiterhin auftritt, müssen Sie den Connector löschen und neu erstellen. Wenn mehrere Instanzen eines Connectors vorhanden sind, verwendet die App möglicherweise die falsche Instanz.
Verknüpfen Sie das Steuerelement „Vertikaler Katalog“ mit der Sammlung azResult, die im vorherigen Schritt erstellt wurde.

Wählen Sie das Galerie-Steuerelement aus und führen Sie im Eigenschaftenbereich die folgenden Aktionen aus.
- Legen Sie DataSource auf azResult fest.
- Wählen Sie ein Layout, das für den Typ der Daten im Index geeignet ist. In diesem Fall haben wir das Layout Titel, Untertitel und Text verwendet.
- Bearbeiten Sie die Felder, und wählen Sie die Felder aus, die Sie visualisieren möchten.
Da wir beim Definieren des Connectors ein Beispielergebnis angegeben haben, erkennt die App die im Index verfügbaren Felder.
Drücken Sie F5, um eine Vorschau der App anzuzeigen.

Bereinigen von Ressourcen

Wenn Sie in Ihrem eigenen Abonnement arbeiten, sollten Sie sich am Ende eines Projekts überlegen, ob Sie die erstellten Ressourcen noch benötigen. Ressourcen, die weiterhin ausgeführt werden, können Sie Geld kosten. Sie können einzelne Ressourcen oder die gesamte Ressourcengruppe mit allen darin enthaltenen Ressourcen löschen.

Sie können Ressourcen im Azure-Portal über den Link Alle Ressourcen oder Ressourcengruppen im linken Navigationsbereich suchen und verwalten.

Denken Sie daran, dass ein kostenloser Suchdienst auf drei Indizes, Indexer und Datenquellen beschränkt ist. Sie können einzelne Elemente über das Azure-Portal löschen, um unter dem Grenzwert zu bleiben.

Nächste Schritte

Power Apps ermöglicht die schnelle Anwendungsentwicklung von benutzerdefinierten Apps. Nun wissen Sie, wie Sie eine Verbindung mit einem Suchindex herstellen. Als Nächstes können Sie sich darüber informieren, wie Sie eine umfassende Visualisierungsoberfläche in einer benutzerdefinierten Power App erstellen.

Lernkatalog für Power Apps