Erstellen von Ressourcen mithilfe der REST-API

  • Artikel

In diesem Tutorial erfahren Sie, wie Sie Ressourcen im Microsoft Purview Data Map erstellen, die Benutzer im Microsoft Purview Data 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

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 Azure Active Directory, und wählen Sie diese Option aus.

  3. Wählen Sie auf der Seite Azure Active Directory 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 Zertifikatgeheimnisse & 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.

  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.

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 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.
    • 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.
    • Wenn Sie eine Anwendung wie Postman verwenden, stellen Sie sicher, dass Ihre Software 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

Anforderungs-URL: https://{accountName}.purview.azure.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

Anforderungs-URL: https://{accountName}.purview.azure.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