Erstellen von Ressourcen mithilfe der REST-API

In diesem Tutorial erfahren Sie, wie Sie Ressourcen in Microsoft Purview Data Map erstellen, die Benutzer in Microsoft Purview Unified Catalog suchen und durchsuchen können.

Hinweis

Wenn Sie die kostenlose Version von Microsoft Purview verwenden, können nur Benutzer in der Rollengruppe "Datenkurator " auf diese Ressourcen zugreifen.

Wenn Sie bereits über Ihren Dienstprinzipal und das Authentifizierungstoken verfügen, können Sie direkt mit den Schritten zum Erstellen von Ressourcen mithilfe der REST-API fortfahren. Befolgen Sie andernfalls diese Anleitung, um die REST-API aufzurufen.

Voraussetzungen

• Wenn Sie nicht über ein Azure-Abonnement verfügen, erstellen Sie ein kostenloses Konto , bevor Sie beginnen.
• Sie müssen über ein vorhandenes Microsoft Purview-Konto verfügen. Wenn dies nicht der Fall ist, überprüfen Sie, ob Ihr organization Zugriff auf die kostenlose Version von Microsoft Purview hat, oder verwenden Sie diese Schnellstartanleitung, um ein Microsoft Purview-Konto zu erstellen.

Erstellen eines Dienstprinzipals (Anwendung)

Damit ein REST-API-Client auf Microsoft Purview zugreifen kann, um Entitäten zu erstellen, muss der Client über einen Dienstprinzipal (Anwendung) und eine Identität verfügen, die Microsoft Purview erkennt und so konfiguriert ist, dass er vertrauenswürdig ist.

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:

1. Melden Sie sich beim Azure-Portal an.

2. Suchen Sie im Portal nach Microsoft Entra ID, und wählen Sie sie aus.

3. Wählen Sie auf der Seite Microsoft Entra ID im linken Bereich App-Registrierungen aus.

4. Wählen Sie Neue Registrierung aus.

5. 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.

6. 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:

1. Wählen Sie in der Liste App-Registrierungen Ihren Dienstprinzipal (Anwendung) aus.
2. Wählen Sie im linken Bereich Zertifikate & Geheimnisse aus.
3. Wählen Sie Neues Clientgeheimnis aus.
4. 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.
5. 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 Berechtigungen zuweisen, damit Ihr Dienstprinzipal auf Ihr Microsoft Purview-Konto zugreifen kann. Welche Berechtigungen Sie zuweisen müssen, hängt davon ab, ob Sie die klassische Microsoft Purview-Benutzeroberfläche oder das neue Microsoft Purview-Portal verwenden.

Wählen Sie die Registerkarte für die von Ihnen verwendete Benutzeroberfläche aus.

Klassisches Governanceportal

1. Navigieren Sie zu Ihrem Microsoft Purview-Governanceportal.

2. Wählen Sie im linken Menü die Data Map aus.

3. Wählen Sie Sammlungen aus.

4. Wählen Sie die Stammsammlung im Menü Sammlungen aus. Dies ist die oberste Sammlung in der Liste und hat denselben 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.

5. Wählen Sie die Registerkarte Rollenzuweisungen aus.

6. Weisen Sie dem zuvor erstellten Dienstprinzipal die Rolle Datenkurator zu. Ausführliche Schritte finden Sie unter Zuweisen von Azure-Rollen mithilfe des Microsoft Purview-Governanceportals.

Neues Microsoft Purview-Portal

1. Fügen Sie Ihren Dienstprinzipal einer Gruppe hinzu, damit ihr eine Rollengruppe in Microsoft Purview zugewiesen werden kann.
2. Fügen Sie Ihren Dienstprinzipal der Datenkurator-Rollengruppe hinzu, um Zugriff auf das Hinzufügen von Entitäten zu haben. Um Ihren Dienstprinzipal der Rollengruppe hinzuzufügen, befolgen Sie diese Anweisungen auf der Seite berechtigungen.

Nachdem Sie Berechtigungen zugewiesen haben, müssen Sie Ihr Authentifizierungstoken sammeln.

1. Senden Sie eine POST-Anforderung an die folgende URL, 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 Microsoft Entra ID 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.
   • resource: Dies sollte "https://purview.azure.net" sein.

   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.
   • Stellen Sie sicher, dass Ihre Software für die Anwendung, die Sie zum Senden Ihrer POST-Anforderung verwenden, auf dem neuesten Stand ist.

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

Erstellen von Ressourcen mithilfe der REST-API

Nachdem Sie nun über ein Token verfügen und sich authentifizieren können, können Sie Ihre Ressourcen erstellen.

Wichtig

Ihre Anforderungs-URL-Endpunkte hängen davon ab, welche Microsoft Purview-Benutzeroberfläche Sie verwenden: die klassische Microsoft Purview-Benutzeroberfläche oder das neue Microsoft Purview-Portal.

Erstellen von Azure-Ressourcen

Hier sehen Sie ein Beispiel, das Sie verwenden können, um Ihre Entitäten für Azure-Ressourcen zu erstellen. In diesem Beispiel wird ein Azure Storage-Konto behandelt, aber Sie können es für alle anderen Azure-Quellen verwenden.

Wichtig

Um dieses Beispiel für Ihre Azure-Ressourcen zu verwenden, ersetzen Sie die folgenden Werte in der Nutzlast:

• typeName
• Besitzer
• qualifiedName
• name
• Experten-ID
• Experten-Info
• Besitzer-ID
• Besitzerinformationen
• Createdby
• Aktualisiertby

Klassisches Governanceportal

Anforderungs-URL: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Neues Microsoft Purview-Portal

Anforderungs-URL: https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Method: POST

Authentifizierung: Verwenden Sie das Token aus dem vorherigen Schritt als Bearertoken.

Nutzlastbeispiel:

{
  "referredEntities": {},
  "entity": {
    "typeName": "azure_storage_account",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "https://exampleaccount.core.windows.net",
      "name": "ExampleStorageAccount",
      "description": null,
      "publicAccessLevel": null
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": " 30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Erstellen von Multicloudressourcen

Hier ist ein Beispiel, das Sie verwenden können, um Ihre Entitäten für Multicloudressourcen zu erstellen. In diesem Beispiel wird eine Snowflake-Ressource erstellt, sie kann jedoch für alle anderen Quellen verwendet werden.

Wichtig

Um dieses Beispiel für Ihre Azure-Ressourcen zu verwenden, ersetzen Sie die folgenden Werte in der Nutzlast:

• typeName
• Besitzer
• qualifiedName
• name
• type
• Experten-ID
• Experten-Info
• Besitzer-ID
• Besitzerinformationen
• Createdby
• Aktualisiertby

Klassisches Governanceportal

Anforderungs-URL: https://{accountName}.purview.azure.com/catalog/api/atlas/v2/entity

Neues Microsoft Purview-Portal

Anforderungs-URL: https://api.purview-service.microsoft.com/catalog/api/atlas/v2/entity

Method: POST

Authentifizierung: Verwenden Sie das Token aus dem vorherigen Schritt als Bearertoken.

Nutzlastbeispiel:

{
  "referredEntities": {},
  "entity": {
    "typeName": "snowflake_table",
    "attributes": {
      "owner": "ExampleOwner",
      "modifiedTime": 0,
      "createTime": 0,
      "qualifiedName": "snowflake://microsoft_partner.east-us-2.azure.snowflakecomputing.com/databases/AZUREPURVIEW_TESTDB/schemas/COMPANY/tables/PROJECT_INFO",
      "name": "PROJECT_INFO",
      "description": null,
      "type": "TABLE"
    },
    "contacts": {
      "Expert": [
        {
          "id": "30435ff9-9b96-44af-a5a9-e05c8b1ae2d2",
          "info": "Example Expert Info"
        }
      ],
      "Owner": [
        {
          "id": "4b27e65f-6a15-4925-a4ef-2e640445079b",
          "info": "Example Owner Info"
        }
      ]
    },
    "status": "ACTIVE",
    "createdBy": "ExampleCreator",
    "updatedBy": "ExampleUpdator",
    "version": 0
  }
}

Nächste Schritte

Verwalten von Datenquellen: Referenz zur Microsoft Purview-Entitäts-REST-API