Aufrufen einer API mit einem Abonnementschlüssel

  • 5 Minuten

Wenn Sie eine API veröffentlichen, möchten Sie in der Regel festlegen, wer darauf über das Gateway zugreifen darf. Abonnementschlüssel sind eine Möglichkeit, den Zugriff auf eine API zu beschränken.

Hier erfahren Sie, wie Sie Ihre APIs mit Abonnementschlüsseln schützen.

Abonnements und Schlüssel

Sie können Ihre APIs mit einem Abonnementschlüssel schützen.

Hinweis

In API Management-Produktionsumgebungen kombinieren Sie in der Regel einen Abonnementschlüssel mit anderen Mechanismen, um Ihre APIs vor nicht autorisierter Verwendung zu schützen, z. B. Zertifikatauthentifizierung oder OAuth 2.0-Autorisierung. Diese werden im Rahmen dieses Moduls nicht behandelt.

Ein Abonnementschlüssel ist eine eindeutige, automatisch generierte Zeichenfolge, die in den Headern der Clientanforderung oder als Abfragezeichenfolge übergeben wird. Der Schlüssel ist einem Abonnement zugeordnet, das sich auf verschiedene Bereiche einschränken lässt. Dadurch können Berechtigungen und Richtlinien präzise konfiguriert werden. Die Hauptbereiche für Abonnements sind:

  • Alle APIs
  • Eine einzige API
  • Produkt

Eine Anwendung, die eine geschützte API aufruft, muss den Schlüssel in der Anforderung enthalten.

Sie können diese Abonnementschlüssel jederzeit neu generieren. Generieren Sie z. B. Abonnementschlüssel neu, wenn Sie vermuten, dass ein Schlüssel für nicht autorisierte Benutzer*innen freigegeben wurde.

Subscription keys.

Jedes Abonnement verfügt über zwei Schlüssel: einen Primär- und einen Sekundärschlüssel. Die Verwendung von zwei Schlüsseln vereinfacht das erneute Generieren eines Schlüssels. Wenn Sie beispielsweise den Primärschlüssel ändern und Downtime vermeiden möchten, verwenden Sie den Sekundärschlüssel in Ihren Apps.

Für Produkte mit aktiviertem Abonnement müssen Sie einen Schlüssel angeben, wenn Sie APIs in diesem Produkt aufrufen. Als Entwickler können Sie einen Schlüssel abrufen, indem Sie eine Abonnementanforderung übermitteln. Dieser Prozess ist zentraler Bestandteil des API Management-Workflows.

Hinweis

Das Erstellen neuer Benutzer und die Vergabe von Abonnementschlüsseln an diese Personen für den API-Zugriff ist ein wichtiger Bestandteil des API Management-Workflows. Diese Schritte werden allerdings nicht in diesem Modul beschrieben.

Aufrufen einer API mit dem Abonnementschlüssel

Anwendungen müssen für alle HTTP-Anforderungen einen gültigen Schlüssel bereitstellen, wenn API-Endpunkte aufgerufen werden, die durch ein Abonnement geschützt sind. Schlüssel können über den Anforderungsheader oder als Abfragezeichenfolge in der URL übergeben werden.

Der Standardname für den Header lautet Ocp-Apim-Subscription-Key. Die Standardabfragezeichenfolge ist subscription-key.

Um Ihre API-Aufrufe zu testen, können Sie das Entwicklerportal (sofern es in Ihrer Dienstebene verfügbar ist), ein Befehlszeilentool wie curl oder andere Tools wie Postman verwenden.

Hier sehen Sie ein Beispiel für eine GET-Anforderung, die mithilfe des curl-Befehls einen Schlüssel im Anforderungsheader übergibt:

curl --header "Ocp-Apim-Subscription-Key: <key string>" https://<apim gateway>.azure-api.net/api/path

Mit dem folgenden curl-Beispielbefehl wird ein Schlüssel in der URL als Abfragezeichenfolge übergeben:

curl https://<apim gateway>.azure-api.net/api/path?subscription-key=<key string>

Wenn der Schlüssel nicht im Header oder als Abfragezeichenfolge in der URL übergeben wird, erhalten Sie vom API-Gateway die Antwort 401 Zugriff verweigert.