Tutorial: Verwenden der REST-APIs

Artikel
08/23/2023

In diesem Tutorial erfahren Sie, wie Sie die REST-APIs der Microsoft Purview-Datenebene verwenden. Jeder, der Daten an Microsoft Purview übermitteln, Microsoft Purview als Teil eines automatisierten Prozesses einbinden oder eine eigene Benutzererfahrung in Microsoft Purview erstellen möchte, kann dazu die REST-APIs verwenden.

Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.

Voraussetzungen

Um zu beginnen, benötigen Sie ein vorhandenes Microsoft Purview-Konto. Wenn Sie über keinen Katalog verfügen, lesen Sie den Schnellstart zum Erstellen eines Microsoft Purview-Kontos.

Erstellen eines Dienstprinzipals (Anwendung)

Damit ein REST-API-Client auf die Microsoft Purview-Datenebenen-APIs zugreifen kann, muss der Client über einen Dienstprinzipal (Anwendung) und eine Identität verfügen, die Microsoft Purview erkennt und so konfiguriert ist, dass sie als vertrauenswürdig konfiguriert ist. Wenn Sie REST-API-Aufrufe ausführen, wird die Identität dieses Dienstprinzipals für die Autorisierung verwendet.

Kunden, die vorhandene Dienstprinzipale (Anwendungs-IDs) verwendet haben, weisen eine hohe Fehlerrate auf. Daher wird empfohlen, einen neuen Dienstprinzipal zum Aufrufen von APIs zu erstellen.

So erstellen Sie einen neuen Dienstprinzipal:

Melden Sie sich beim Azure-Portal an.
Suchen Sie im Portal nach Azure Active Directory, und wählen Sie diese Option aus.
Wählen Sie auf der Seite Azure Active Directory im linken Bereich App-Registrierungen aus.
Wählen Sie Neue Registrierung aus.
Gehen Sie auf der Seite Anwendung registrieren wie
1. Geben Sie einen Namen für die Anwendung (dienstprinzipalname) ein.
2. Wählen Sie Nur Konten in diesem Organisationsverzeichnis (<nur Name> Ihres Mandanten – Einzelner Mandant) aus.
3. Wählen Sie für Umleitungs-URI (optional)die Option Web aus, und geben Sie einen Wert ein. Dieser Wert muss kein gültiger Endpunkt sein. https://exampleURI.com wird.
4. Wählen Sie Registrieren aus.
Kopieren Sie auf der Seite für den neuen Dienstprinzipal die Werte des Anzeigenamens und der Anwendungs-ID (Client), um sie später zu speichern.

Die Anwendungs-ID ist der client_id Wert im Beispielcode.

Um den Dienstprinzipal (Anwendung) verwenden zu können, müssen Sie das Kennwort des Dienstprinzipals kennen, das sie finden können:

Suchen Sie im Azure-Portal nach Azure Active Directory, wählen Sie diese Option aus, und wählen Sie dann im linken Bereich App-Registrierungen aus.
Wählen Sie Ihren Dienstprinzipal (Anwendung) aus der Liste aus.
Wählen Sie im linken Bereich Zertifikatgeheimnisse & aus.
Wählen Sie Neues Clientgeheimnis aus.
Geben Sie auf der Seite Geheimen Clientschlüssel hinzufügen eine Beschreibung ein, wählen Sie unter Läuft ab eine Ablaufzeit aus, und wählen Sie dann Hinzufügen aus.

Auf der Seite Geheime Clientschlüssel ist die Zeichenfolge in der Spalte Wert Ihres neuen Geheimnisses Ihr Kennwort. Speichern Sie diesen Wert.

Einrichten der Authentifizierung mithilfe des Dienstprinzipals

Nachdem der neue Dienstprinzipal erstellt wurde, müssen Sie die Datenebenenrollen Ihres Purview-Kontos dem oben erstellten Dienstprinzipal zuweisen. Führen Sie die folgenden Schritte aus, um die richtige Rolle zuzuweisen, um eine Vertrauensstellung zwischen dem Dienstprinzipal und dem Purview-Konto herzustellen:

Navigieren Sie zu Ihrem Microsoft Purview-Governanceportal.
Wählen Sie im linken Menü die Data Map aus.
Wählen Sie Sammlungen aus.
Wählen Sie die Stammsammlung im Menü Sammlungen aus. Dies ist die oberste Sammlung in der Liste und hat den gleichen Namen wie Ihr Microsoft Purview-Konto.

Hinweis

Sie können Ihre Dienstprinzipalberechtigung auch allen Untersammlungen anstelle der Stammsammlung zuweisen. Alle APIs werden jedoch auf diese Sammlung (und Untersammlungen, die Berechtigungen erben) festgelegt, und Benutzer, die versuchen, die API für eine andere Sammlung aufzurufen, erhalten Fehler.
Wählen Sie die Registerkarte Rollenzuweisungen aus.
Weisen Sie dem zuvor erstellten Dienstprinzipal die folgenden Rollen zu, um auf verschiedene Datenebenen in Microsoft Purview zuzugreifen. Ausführliche Schritte finden Sie unter Zuweisen von Azure-Rollen mithilfe des Microsoft Purview-Governanceportals.
- Rolle "Datenkurator" für den Zugriff auf die Katalogdatenebene.
- Die Rolle "Datenquellenadministrator" für den Zugriff auf die Scandatenebene.
- Sammlung Admin Rolle für den Zugriff auf Kontodatenebene und Metadatenrichtlinie Datenebene.
- Rolle "Richtlinienautor" für den Zugriff auf die DevOps-Richtlinien-API
Hinweis

Nur Mitglieder der Rolle Sammlung Admin können Datenebenenrollen in Microsoft Purview zuweisen. Weitere Informationen zu Microsoft Purview-Rollen finden Sie unter Access Control in Microsoft Purview.

Token abrufen

Sie können eine POST-Anforderung an die folgende URL senden, um das Zugriffstoken abzurufen.

https://login.microsoftonline.com/{your-tenant-id}/oauth2/token

Sie können Ihre Mandanten-ID finden, indem Sie im Azure-Portal nach Mandanteneigenschaften suchen. Die ID ist auf der Eigenschaftenseite des Mandanten verfügbar.

Die folgenden Parameter müssen an die obige URL übergeben werden:

client_id: Client-ID der Anwendung, die in Azure Active Directory registriert ist und einer Datenebenenrolle für das Microsoft Purview-Konto zugewiesen ist.
client_secret: Geheimer Clientschlüssel, der für die oben genannte Anwendung erstellt wurde.
grant_type: Dies sollte "client_credentials" sein.
ressource: 'https://purview.azure.net'

Hier sehen Sie eine BEISPIEL-POST-Anforderung in PowerShell:

$tenantID = "12a345bc-67d1-ef89-abcd-efg12345abcde"

$url = "https://login.microsoftonline.com/$tenantID/oauth2/token"
$params = @{ client_id = "a1234bcd-5678-9012-abcd-abcd1234abcd"; client_secret = "abcd~a1234bcd56789012abcdabcd1234abcd"; grant_type = "client_credentials"; resource = ‘https://purview.azure.net’ }

Invoke-WebRequest $url -Method Post -Body $params -UseBasicParsing | ConvertFrom-Json

Beispielantworttoken:

    {
        "token_type": "Bearer",
        "expires_in": "86399",
        "ext_expires_in": "86399",
        "expires_on": "1621038348",
        "not_before": "1620951648",
        "resource": "https://purview.azure.net",
        "access_token": "<<access token>>"
    }

Tipp

Wenn Sie eine Fehlermeldung mit folgendem Text erhalten: Die tokenübergreifende Einlösung ist nur für den Clienttyp "Single-Page Application" zulässig.

Überprüfen Sie Ihre Anforderungsheader, und vergewissern Sie sich, dass Ihre Anforderung nicht den Header "origin" enthält.
Vergewissern Sie sich, dass Der Umleitungs-URI in Ihrem Dienstprinzipal auf web festgelegt ist.
Wenn Sie eine Anwendung wie Postman verwenden, stellen Sie sicher, dass Ihre Software auf dem neuesten Stand ist.

Verwenden Sie das oben genannte Zugriffstoken, um die Datenebenen-APIs aufzurufen.

Nächste Schritte

Verwalten von Datenquellen : Rest-APIs der Microsoft Purview-Datenebene

Teilen über