API-Gateway-Konzepte

Im API-Gateway-Service stellt ein API-Gateway eine virtuelle Netzwerk-Appliance in einem regionalen Subnetz dar.

Ein API-Gateway leitet eingehenden Traffic an Backend-Services weiter, einschließlich öffentlicher, privater und Partner-HTTP-APIs sowie OCI Functions. Jedes API-Gateway ist ein privater Endpunkt, den Sie optional über eine öffentliche IP-Adresse als öffentliches API-Gateway angeben können:

• Auf ein privates API-Gateway können nur Ressourcen im selben privaten Netzwerk (VCN) oder Ressourcen in einem anderen privaten oder On-Premise-Netzwerk zugreifen, die per Peering mit diesem privaten Netzwerk verbunden sind. Ein privates API-Gateway verfügt über eine private IP-Adresse und einen automatisch generierten Hostnamen im Format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Beachten Sie, dass der Hostname zwar öffentlich aus dem Internet aufgelöst werden kann, aber in die private IP-Adresse des API-Gateways aufgelöst wird. Der Traffic zur privaten IP-Adresse kann nicht über das öffentliche Internet weitergeleitet werden. Nur Clients im VCN können auf das API-Gateway zugreifen. Die öffentliche DNS-Auflösbarkeit einer privaten IP-Adresse wird erwartet und unterstützt verschiedene Netzwerkkonfigurationen innerhalb von OCI-Umgebungen.
• Ein öffentliches API-Gateway ist öffentlich zugänglich und kann über das Internet erreicht werden, sofern ein Internetgateway im VCN des API-Gateways vorhanden ist. Ein öffentliches API-Gateway verfügt sowohl über eine private IP-Adresse als auch über eine öffentliche IP-Adresse und einen automatisch generierten Hostnamen im Format <gatewayidentifier>.apigateway.<region-identifier>.oci.customer-oci.com. Der generierte Hostname wird vom Internet zur öffentlichen IP-Adresse aufgelöst, sodass internetbasierte Clients auf das API-Gateway zugreifen können.

Um High Availability sicherzustellen, können Sie API-Gateways nur in regionalen Subnetzen (und nicht in AD-spezifischen Subnetzen) erstellen. Sie können private API-Gateways in privaten oder öffentlichen Subnetzen erstellen. Öffentliche API-Gateways können jedoch nur in öffentlichen Subnetzen erstellt werden. Der API Gateway-Service ist im Geltungsbereich regional und fehlertolerant in Availability-Domains (in mehreren AD-Regionen) und Faultdomains (in einzelnen AD-Regionen). In Regionen mit mehreren ADs wählt der API-Gateway-Service automatisch eine aktive Availability-Domain aus, um den API-Gatewayendpunkt zu beenden. Beachten Sie, dass je nach Quelle und Ziel des Traffics Traffic über Availability-Domains geleitet werden kann. Wenn eine Availability-Domain oder Faultdomain ausfällt, verarbeitet der API-Gateway-Service automatisch Failover und leitet Traffic an eine funktionierende Availability-Domain oder Faultdomain weiter.

Ein API-Gateway ist an eine bestimmte VNIC gebunden.

Sie erstellen ein API-Gateway in einem Compartment in Ihrem Mandanten. Jedes API-Gateway verfügt über ein einzelnes Frontend sowie über null oder mehr Backends. Außerdem sind null oder mehr APIs als API-Deployments darin bereitgestellt.

Im API Gateway-Service stellt eine API ein Set von Backend-Ressourcen dar und definiert Methoden (z.B. GET, PUT), die für die einzelnen Backend-Ressourcen als Antwort auf die von einem API-Client gesendeten Anforderungen ausgeführt werden können.

Um ein API-Gateway zur Verarbeitung von API-Anforderungen zu aktivieren, müssen Sie die API in dem API-Gateway bereitstellen, indem Sie ein API-Deployment erstellen.

Um eine API in einem API-Gateway bereitzustellen, können Sie eine API-Ressource im API Gateway-Service erstellen. Eine API-Ressource enthält eine API-Beschreibung, die die API-Ressource definiert. Beachten Sie, dass das Erstellen einer API-Ressource optional ist. Sie können eine API in einem API-Gateway bereitstellen, ohne eine API-Ressource im API Gateway-Service zu erstellen.

Im API-Gateway-Service stellt ein API-Deployment das Instrument dar, mit dem Sie eine API in einem API-Gateway bereitstellen. Bevor das API-Gateway Anforderungen an die API verarbeiten kann, müssen Sie ein API-Deployment erstellen.

Beim Erstellen eines API-Deployments legen Sie Eigenschaften für das API-Deployment fest, einschließlich einer API-Deployment-Spezifikation. Jedes API-Deployment verfügt über eine API-Deployment-Spezifikation.

Sie können mehrere APIs im selben API-Gateway bereitstellen, was bedeutet, dass ein einzelnes API-Gateway mehrere API-Deployments hosten kann.

Im API-Gateway-Service beschreibt eine API-Deployment-Spezifikation einige Aspekte eines API-Deployments.

Beim Erstellen des API-Deployments legen Sie Eigenschaften für das API-Deployment fest, einschließlich einer API-Deployment-Spezifikation. Jedes API-Deployment verfügt über eine API-Deployment-Spezifikation. Sie können eine API-Deployment-Spezifikation folgendermaßen erstellen:

• Indem Sie Dialogfelder in der Konsole verwenden
• Indem Sie Ihren bevorzugten JSON-Editor zum Erstellen einer JSON-Datei verwenden
• Indem Sie eine API-Beschreibung verwenden, die Sie aus einer API-Beschreibungsdatei hochgeladen haben und die in einer unterstützten Sprache geschrieben ist (Beispiel: OpenAPI-Spezifikation Version 3.0)

Jede API-Deployment-Spezifikation beschreibt mindestens eine Backend-Ressource, die Route zu den einzelnen Backend-Ressourcen und die Methoden (z.B. GET, PUT), die für die einzelnen Ressourcen ausgeführt werden können. Die API-Deployment-Spezifikation beschreibt, wie das API-Gateway in das Backend integriert wird, sodass diese Methoden ausgeführt werden können. Die API-Deployment-Spezifikation kann auch Anforderungs- und Antwort-Policys enthalten.

Im API Gateway-Service können Sie optional eine API-Ressource erstellen. Eine API-Ressource ist die Entwurfszeitdarstellung einer API. Sie können eine API-Ressource verwenden, um eine API in einem API-Gateway bereitzustellen.

Eine API-Beschreibung definiert eine API-Ressource, einschließlich:

• verfügbarer Endpunkte
• verfügbarer Vorgänge für jeden Endpunkt
• Parametern, die für jeden Vorgang eingegeben und ausgegeben werden können
• Authentifizierungsmethoden

Wenn Sie eine API-Ressource verwenden, um eine API in einem API-Gateway bereitzustellen, füllt die API-Beschreibung einige Eigenschaften der API-Deployment-Spezifikation vorab auf.

Sie importieren die API-Beschreibung aus einer Datei (manchmal auch als "API-Spezifikation" bezeichnet), die in einer unterstützten Sprache geschrieben ist. Derzeit werden OpenAPI-Spezifikation Version 2.0 (ehemals Swagger-Spezifikation 2.0) und Version 3.0 unterstützt.

Sie können auch ein SDK aus der API-Beschreibungsdatei generieren.

Beachten Sie, dass die Erstellung einer API-Ressource im API Gateway-Service optional ist. Sie können eine API in einem API-Gateway bereitstellen, ohne eine API-Ressource im API Gateway-Service zu erstellen. Beachten Sie auch, dass Sie zunächst eine API-Ressource ohne API-Beschreibung erstellen und später eine API-Beschreibung hinzufügen können.

Im API-Gateway-Service stellt ein Frontend das Instrument dar, das Anforderungen in ein API-Gateway fließen lässt. Ein API-Gateway kann entweder über ein öffentliches Frontend oder ein privates Frontend verfügen:

• Ein öffentliches Frontend gibt die APIs an, die über eine öffentliche IP-Adresse in einem API-Gateway bereitgestellt werden.
• Ein privates Frontend gibt die APIs an, die über einen privaten Endpunkt in einem API-Gateway zu einem VCN bereitgestellt werden.

Im API-Gateway-Service stellt ein Backend das Instrument dar, mit dem ein Gateway Anforderungen an die Backend-Services weiterleitet, die APIs implementieren. Wenn Sie ein privates Endpunkt-Backend zu einem API-Gateway hinzufügen, erteilen Sie dem API-Gateway Zugriff auf das VCN, das mit diesem privaten Endpunkt verknüpft ist.

Sie können einem API-Gateway auch Zugriff auf weitere Oracle Cloud Infrastructure-Services als Backends erteilen. Beispiel: Sie können einem API-Gateway Zugriff auf OCI Functions erteilen, damit Sie eine API erstellen und bereitstellen können, die durch eine serverlose Funktion gesichert ist.

API-Provider sind Personen oder Teams, die APIs entwerfen, implementieren, bereitstellen und betreiben. Diese Benutzer interagieren mit Schnittstellen wie der Oracle Cloud Infrastructure-Konsole, dem SDK, der CLI und dem Terraform-Provider. Sie verwenden den API Gateway-Service, um APIs bereitzustellen, zu überwachen und zu betreiben. Bei einigen Organisationen wird die API-Providerrolle weiter segmentiert, z.B. in:

• API-Entwickler, die für die Erstellung von APIs und deren Bereitstellung in API-Gateways verantwortlich sind.
• API-Planmanager, die für die Überwachung und Verwaltung der API-Nutzung verantwortlich sind (z.B. durch Definition von Nutzungsplänen und Abonnenten).
• API Gateway-Manager, die für die Verwaltung von API-Gateways verantwortlich sind, normalerweise in der Produktion.

API-Consumers sind Personen oder Teams, die Apps und Services (API-Clients) erstellen und eine oder mehrere APIs eines API-Providers nutzen möchten. Der API-Consumer verwendet in der Regel nicht den gleichen Oracle Cloud Infrastructure-Mandanten wie der API-Provider. Der API-Consumer ist ein Kunde des API-Providers.

API-Clients sind Anwendungen oder Geräte, die von einem API-Consumer erstellt wurden. Der API-Client ruft die API zur Laufzeit auf, indem Anforderungen an das API-Gateway gesendet werden, auf dem die API bereitgestellt wird. API-Clients kommunizieren über HTTPS mit dem API-Gateway (einschließlich HTTP/2). API-Clients authentifizieren sich in der Regel über OAuth, Basisauthentifizierung oder mTLS bei der API und verwenden möglicherweise ein anderes Token wie einen API-Schlüssel für Messung und Monetarisierung.

Ein Endbenutzer ist ein Benutzer eines API-Clients und wird in Bezug auf die Autorisierung manchmal auch als "Ressourceneigentümer" bezeichnet. Der Endbenutzer interagiert immer nur über den API-Client mit einer API und ist sich in der Regel der API selbst nicht bewusst. Der Endbenutzer ist ein Kunde des API-Consumers.

Im API Gateway-Service können API-Planmanager die Nutzung ihrer APIs verwalten und überwachen, indem sie Nutzungsplanressourcen und Subscriber-Ressourcen definieren.

Eine Nutzungsplanressource umfasst Berechtigungen. Jeder Anspruch gibt Folgendes an:

• Ein Ratenlimit: Die maximal zulässige Anzahl von API-Anforderungen pro Sekunde.
• Eine Quota: Die Gesamtanzahl der in einem bestimmten Zeitraum (zwischen einer Minute und einem Monat) zulässigen API-Aufrufe.
• Mindestens ein Ziel-API-Deployment. Die API-Deployments, auf die Abonnenten des Nutzungsplans zugreifen können.

Sie können ein API-Deployment als Ziel in mehreren Berechtigungen in verschiedenen Nutzungsplänen angeben, jedoch nicht in mehreren Berechtigungen im selben Nutzungsplan. Eine Berechtigung kann API-Deployments aus verschiedenen API-Gateways enthalten.

Als API-Planmanager können Sie mit Nutzungsplänen den API-Zugriff kontrollieren, der für Ihre Kunden (API-Consumer) und deren API-Clients verfügbar ist. Sie können den API-Zugriff Tariflimits und Quoten unterliegen, die auf bestimmte Kundenanforderungen zugeschnitten sind, sodass Sie verschiedene Zugriffsebenen für verschiedene Kunden einrichten können.

Eine Subscriber-Ressource umfasst:

• Ein einzelner API-Consumer.
• Clientnamen und Clienttoken zur eindeutigen Identifizierung von API-Clients, die vom API-Consumer erstellt wurden.
• Nutzungspläne, für die der API-Consumer und seine API-Clients abonniert sind.

Als API-Planmanager können Sie Abonnenten für Ihre Kunden (API-Consumer) erstellen, um die Nutzungspläne anzugeben, die ihren API-Clients Zugriff auf Ihre APIs gewähren.

Damit ein API-Deployment zur Aufnahme in einen Nutzungsplan berechtigt ist, geben Sie den Speicherort des Clienttokens an, das in Anforderungen übergeben wird. Nachdem das API-Deployment in einen Nutzungsplan aufgenommen wurde, müssen Anforderungen das Clienttoken an diesem Speicherort enthalten, um auf das API-Deployment zugreifen zu können. Sie geben den Speicherort des Clienttokens in einer Nutzungsplananforderungs-Policy in der API-Deployment-Spezifikation an. (Beachten Sie, dass die Client-Token, die Sie in Subscriber-Ressourcen definieren, nur zu Nutzungsplan-Reportingzwecken und nicht zur Clientauthentifizierung und -autorisierung dienen.)

Im API-Gateway-Service stellt eine Route die Zuordnung zwischen einem Pfad, einer oder mehreren Methoden und einem Backend-Service dar. Routen werden in API-Deployment-Spezifikationen definiert.

Im API Gateway-Service sind verschiedene Policy-Typen verfügbar:

• Eine Anforderungs-Policy beschreibt Aktionen, die für eine eingehende Anforderung von einem API-Client durchgeführt werden, bevor diese an ein Backend gesendet wird.
• Eine Antwort-Policy beschreibt Aktionen, die für eine von einem Backend zurückgegebene Antwort durchgeführt werden, bevor diese an einen API-Client gesendet wird
• Eine Logging-Policy beschreibt, wie Informationen zu Anforderungen und Antworten, die über ein API-Gateway gesendet werden, und Informationen zur Verarbeitung in einem API-Gateway gespeichert werden.

Mit Anforderungs-Policys und/oder Antwort-Policys können Sie:

• die Anzahl von Anforderungen begrenzen, die an Backend-Services gesendet werden
• CORS-(Cross-Origin Resource Sharing-)Support aktivieren
• Authentifizierung und Autorisierung bereitstellen
• Anforderungen validieren, bevor sie an Backend-Services gesendet werden
• eingehende Anforderungen und ausgehende Antworten ändern
• API-Deployments für die Aufnahme in Nutzungspläne zur Überwachung und Verwaltung des Abonnentenzugriffs qualifizieren

Sie können einer API-Deployment-Spezifikation Policys hinzufügen, die global für alle Routen in der API-Deployment-Spezifikation gelten, sowie Policys, die nur für bestimmte Routen gelten.

Hinweis: API-Gateway-Policys unterscheiden sich von IAM-Policys, die den Zugriff auf Oracle Cloud Infrastructure-Ressourcen steuern.