Nutzungsplan erstellen

So erstellen Sie mit der Konsole einen neuen Nutzungsplan und mindestens eine Berechtigung:

1. Wählen Sie auf der Listenseite Nutzungspläne die Option Nutzungsplan erstellen aus. Wenn Sie Hilfe bei der Suche nach der Listenseite benötigen, finden Sie weitere Informationen unter Nutzungspläne auflisten.

2. Geben Sie die folgenden Werte für den Nutzungsplan an:

   • Name: Der Name des neuen Nutzungsplans. Beispiel: Gold-usage-plan. Vermeiden Sie die Eingabe von vertraulichen Informationen.
   • Compartment: Das Compartment, zu dem der neue Nutzungsplan gehören soll.
3. Wählen Sie optional Erweiterte Optionen, und geben Sie Folgendes an:
   • Tags: Wenn Sie über Berechtigungen zum Erstellen von Ressourcen verfügen, können Sie auch Freiformtags auf diese Ressource anwenden. Um ein definiertes Tag anzuwenden, benötigen Sie Die Berechtigungen zum Verwenden des Tag-Namespace. Weitere Informationen zu Tagging finden Sie unter Ressourcentags. Wenn Sie nicht sicher sind, ob Tags angewendet werden sollen, überspringen Sie diese Option, oder fragen Sie einen Administrator. Sie können Tags später anwenden.

4. Wählen Sie Weiter aus, um die API-Deployments anzugeben, auf die API-Consumer und API-Clients, die den Nutzungsplan abonniert haben, Zugriff haben.

   Ein Nutzungsplan umfasst Berechtigungen. Jede Berechtigung gibt eine oder mehrere Ziel-API-Deployments an, an die Abonnenten des Nutzungsplans Anforderungen senden dürfen, sowie die Anzahl der Anforderungen, zu denen sie berechtigt sind.

5. Gehen Sie auf der Seite Berechtigungen wie folgt vor:

   1. Wählen Sie Berechtigung erstellen aus, und geben Sie Details für den ersten Anspruch des Nutzungsplans an:

      • Name: Der Name der neuen Berechtigung. Berechtigungsnamen müssen innerhalb eines Nutzungsplans eindeutig sein. Beispiel: Entitlement1. Vermeiden Sie die Eingabe von vertraulichen Informationen.
      • Beschreibung: Eine Beschreibung der neuen Berechtigung. Beispiel: Basic entitlement for all usage plans. Vermeiden Sie die Eingabe von vertraulichen Informationen.
      • Ratenlimit: (Optional) Wählen Sie Ratenlimit aktivieren aus, um eine maximale Anzahl von Anforderungen anzugeben, die pro Sekunde als Anforderungen pro Sekunde zulässig sind.
      • Quota: (Optional) Wählen Sie Quota aktivieren aus, um eine maximale Anzahl von Anforderungen anzugeben, die in einem bestimmten Zeitraum zulässig sein sollen:
        • Anforderungen: Maximale Anzahl zuzulassende Anforderungen.
        • Periode: Zeitraum, für den die maximale Anzahl von Anforderungen gilt. Eine der Optionen Minute, Stunde, Tag, Woche oder Monat.

        • Policy zurücksetzen: Wann wird die Anzahl der Anforderungen auf Null zurückgesetzt? Die Zurücksetzungsrichtlinie für den Kalender wird unterstützt. Mit der Policy zum Zurücksetzen des Kalenders wird die Anzahl der Anfragenummern zu Beginn jedes neuen Zeitraums auf Null zurückgesetzt, wie unter Periode angegeben.

          Beispiel: Wenn Periode auf Tag gesetzt ist, wird die Anzahl der Anforderungsnummern bei der ersten Erstellung des Anspruchs zunächst auf null gesetzt. Die Anzahl wird dann zu Beginn des folgenden Tages (um Mitternacht UTC) auf Null zurückgesetzt. Die Anzahl wird zu Beginn des nächsten Tages auf Null zurückgesetzt usw.

        • Vorgang bei Verletzung: Was geschieht, wenn die maximale Anzahl von Anforderungen im angegebenen Zeitraum überschritten wird. Wenn Sie Ablehnen angeben, werden zusätzliche Anforderungen im Zeitraum abgelehnt und eine HTTP-429 Too Many Requests-Antwort zurückgegeben. Die Antwort enthält den Header Retry-After, der angibt, wie lange gewartet werden soll, bevor eine neue Anforderung gestellt wird. Wenn Sie Zulassen angeben, sind weitere Anforderungen im Zeitraum weiterhin zulässig.
      • Ziel-Deployment: Wählen Sie Deployment hinzufügen aus, um das erste API-Deployment anzugeben, das in die Berechtigung aufgenommen werden soll:
        • Gateway: Wählen Sie das API-Gateway aus, auf dem das API-Deployment erstellt wurde. Das API-Gateway kann zu demselben Compartment wie der Nutzungsplan gehören, muss aber nicht.
        • Deployment: Wählen Sie das API-Deployment aus, das Sie in die Berechtigung aufnehmen möchten. Das API-Deployment kann zu demselben Compartment wie der Nutzungsplan gehören, muss jedoch nicht.

          Beachten Sie, dass Sie das API-Deployment bereits für die Aufnahme in den Nutzungsplan qualifiziert haben müssen, indem Sie den Speicherort eines Clienttokens angeben (siehe API-Deployment für die Aufnahme in einen Nutzungsplan qualifizieren).

        Wählen Sie Speichern aus, um Details des ersten API-Deployments zu speichern, das in der Berechtigung enthalten ist. Wählen Sie optional erneut Deployment hinzufügen aus, um weitere API-Deployments anzugeben, die in die erste Berechtigung des Nutzungsplans aufgenommen werden sollen.

   2. Wählen Sie Speichern aus, um die erste Berechtigung des Nutzungsplans zu speichern.
   3. Wählen Sie optional erneut die Option Berechtigung erstellen, und geben Sie Details für weitere Berechtigungen an, die in den Nutzungsplan aufgenommen werden sollen.
6. Wählen Sie Weiter aus, um die Details zu prüfen, die Sie für den Nutzungsplan eingegeben haben.
7. Wählen Sie Erstellen aus, um den Nutzungsplan zu erstellen.

   Es kann einige Minuten dauern, bis der neue Nutzungsplan erstellt wird. Während der Erstellung wird der Nutzungsplan mit dem Status "Wird erstellt" auf der Seite Nutzungspläne angezeigt. Sobald er erfolgreich erstellt wurde, wird der neue Nutzungsplan mit dem Status "Aktiv" angezeigt.

   Anstatt den neuen Nutzungsplan sofort zu erstellen, können Sie ihn später mit Resource Manager und Terraform erstellen. Wählen Sie dazu Als Stack speichern aus, um die Ressourcendefinition als Terraform-Konfiguration zu speichern. Weitere Informationen zum Speichern von Stacks aus Ressourcendefinitionen finden Sie unter Stacks auf der Seite "Ressourcen erstellen" erstellen.

8. Wenn Sie mehr als ein paar Minuten darauf gewartet haben, dass der Nutzungsplan mit dem Status "Aktiv" angezeigt wird (oder wenn der Erstellungsvorgang des Nutzungsplans nicht erfolgreich war):

   1. Wählen Sie den Namen des Nutzungsplans aus, und wählen Sie Arbeitsanforderungen aus, um einen Überblick über den Erstellungsvorgang des Nutzungsplans anzuzeigen.
   2. Wählen Sie den Vorgang Nutzungsplan erstellen aus, um weitere Informationen zum Vorgang anzuzeigen (einschließlich Fehlermeldungen, Logmeldungen und Status der zugehörigen Ressourcen).
   3. Wenn der Vorgang zum Erstellen des Nutzungsplans nicht erfolgreich war und Sie die Ursache des Problems nicht in den Arbeitsanforderungsinformationen diagnostizieren können, gehen Sie zu API-Gateway-Fehler beheben.

So erstellen Sie einen neuen Nutzungsplan und mindestens eine Berechtigung mit der CLI:

1. Erstellen Sie mit Ihrem bevorzugten JSON-Editor eine Nutzungsplandefinitionsdatei im folgenden Format:

   {
       "displayName": "<usage-plan-name>",
       "entitlements": [{
           "name": "<entitlement-name>",
           "description": "<entitlement-description>",
           "rateLimit": {
               "value": <rate-limit-value>,
               "unit": "<rate-limit-unit>"
           },
           "quota": {
               "value": <quota-value>,
               "unit": "<quota-unit>",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "<REJECT|ALLOW>"
           },
           "targets": [{
               "deploymentId": "<target-deployment-ocid>"
           }]
       }],
       "compartmentId": "<compartment-ocid>",
       "freeformTags": {},
       "definedTags": {}
   }

   Dabei gilt:

   • "displayName": "<usage-plan-name>" ist der Name des neuen Nutzungsplans. Beispiel: "displayName": "Gold-usage-plan". Vermeiden Sie die Eingabe von vertraulichen Informationen.
   • "entitlements": [{...}] gibt Details einer oder mehrerer Berechtigungen an, wobei:
     • "name": "<entitlement-name>" ist der Name einer neuen Berechtigung. Berechtigungsnamen müssen in einem Nutzungsplan eindeutig sein. Beispiel: "Entitlement1". Vermeiden Sie die Eingabe von vertraulichen Informationen.
     • "description": "<entitlement-description>" ist eine Beschreibung der neuen Berechtigung. Beispiel: "description": "Basic entitlement for all usage plans". Vermeiden Sie die Eingabe von vertraulichen Informationen..
     • "rateLimit": {…} gibt optional eine maximale Anzahl von Anforderungen an, die pro Sekunde zulässig sind. Wenn Sie ein Satzlimit definieren, müssen Sie Werte für Folgendes einschließen:
       • "value": <rate-limit-value> ist die maximal zulässige Anzahl von Anforderungen. Beispiel: "value": 100.
       • "unit": "<rate-limit-unit>" ist die Zeiteinheit der Ratenbegrenzung. Muss auf "SECOND" gesetzt werden.
     • "quota": {…} gibt optional eine maximale Anzahl von Anforderungen an, die in einem bestimmten Zeitraum zulässig sind. Wenn Sie eine Quota definieren, müssen Sie Werte für Folgendes einschließen:
       • "value": <quota-value> ist die maximale Anzahl von Anforderungen, die pro Zeitraum zulässig sind. Beispiel: "value": 1000
       • "unit": "<quota-unit>" ist der Zeitraum, für den die maximale Anzahl von Anforderungen gilt. Muss auf MINUTE, HOUR, DAY, WEEK oder MONTH gesetzt werden. Beispiel: "unit": "MONTH".
       • "resetPolicy": "CALENDAR" ist, wenn die Anzahl der Anforderungen auf null zurückgesetzt wird. Die Policy zum Zurücksetzen von CALENDAR wird unterstützt. Mit der Rücksetzungs-Policy CALENDAR wird die Anzahl der Anforderungsnummern zu Beginn jedes neuen Zeitraums auf null zurückgesetzt, wie mit "unit" angegeben.

         Beispiel: Wenn "unit": "DAY" verwendet wird, wird die Anzahl der Anforderungsnummern beim ersten Erstellen der Berechtigung zunächst auf Null gesetzt. Die Zählung wird dann zu Beginn des folgenden Tages (d.h. um Mitternacht UTC) auf Null zurückgesetzt. Die Anzahl wird zu Beginn des nächsten Tages auf Null zurückgesetzt usw.

       • "operationOnBreach": "<REJECT|ALLOW>" gibt an, was geschieht, wenn die maximale Anzahl von Anforderungen im Zeitraum der Quota überschritten wird. Wenn Sie REJECT angeben, werden zusätzliche Anforderungen im Zeitraum abgelehnt und eine HTTP-429 Too Many Requests-Antwort zurückgegeben. Die Antwort enthält den Retry-After-Header, der angibt, wie lange vor einer neuen Anforderung gewartet werden soll. Wenn Sie ALLOW angeben, sind zusätzliche Anforderungen im Zeitraum weiterhin zulässig. Beispiel: "operationOnBreach": "REJECT"
     • "targets": [{…}] gibt mindestens ein Ziel-API-Deployment an, auf das Abonnenten des Nutzungsplans zugreifen dürfen. Dabei gilt:
       • "deploymentId": "<target-deployment-ocid>" ist die OCID des API-Deployments, das Sie in die Berechtigung aufnehmen möchten. Das API-Deployment kann zu demselben Compartment wie der Nutzungsplan gehören, muss jedoch nicht. Beispiel: "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"

         Beachten Sie, dass Sie das API-Deployment bereits für die Aufnahme in den Nutzungsplan qualifiziert haben müssen, indem Sie den Speicherort eines Clienttokens angeben (siehe API-Deployment für die Aufnahme in einen Nutzungsplan qualifizieren).

   • "compartmentId": "<compartment-ocid>" ist die OCID des Compartments, zu dem der neue Nutzungsplan gehört. Beispiel: "ocid1.compartment.oc1..aaaaaaaa7______ysq"

   Beispiel:

   {
       "displayName": "Gold-usage-plan",
       "entitlements": [{
           "name": "Entitlement1",
           "description": "Basic entitlement for all usage plans",
           "rateLimit": {
               "value": 100,
               "unit": "SECOND"
           },
           "quota": {
               "value": 1000,
               "unit": "MONTH",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
           }]
       },
       {
           "name": "Entitlement2",
           "description": "Gold plan entitlement",
           "rateLimit": {
               "value": 200,
               "unit": "SECOND"
           },
           "quota": {
               "value": 5000,
               "unit": "WEEK",
               "resetPolicy": "CALENDAR",
               "operationOnBreach": "REJECT"
           },
           "targets": [{
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaab______pwa"
             },
             {
               "deploymentId": "ocid1.apideployment.oc1..aaaaaaaaac______nxd"
             }
           ]
         }
       ],
       "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq"
   }

2. Speichern Sie die Nutzungsplandefinitionsdatei mit einem Namen Ihrer Wahl. Zum Beispiel, gold-usageplan.json
3. Verwenden Sie die Nutzungsplandefinitionsdatei, um einen Nutzungsplan mit der CLI zu erstellen:
   1. Konfigurieren Sie die Clientumgebung zur Verwendung der CLI (Clientumgebung zur Verwendung der CLI für API-Gateway-Entwicklung konfigurieren).

   2. Öffnen Sie eine Eingabeaufforderung, und führen Sie oci api-gateway usage-plan create aus, um den Nutzungsplan aus der Nutzungsplandefinitionsdatei zu erstellen:

      oci api-gateway usage-plan create --from-json file://<usageplan-definition>.json

      Dabei gilt:

      • --from-json file://<usageplan-definition>.json ist die Datei mit der Nutzungsplandefinition, einschließlich eines Pfads.

      Beispiel:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json

      Die Antwort auf den Befehl umfasst Folgendes:

      • Die OCID des Nutzungsplans und andere Details.
      • Den Lebenszyklusstatus (Beispiel: ACTIVE, FAILED).
      • Die ID der Arbeitsanforderung zum Erstellen des Nutzungsplans (Details der Arbeitsanforderungen sind für sieben Tage nach Abschluss, Abbruch oder Fehler verfügbar).

      Wenn der Befehl die Steuerung erst dann zurückgeben soll, wenn der Nutzungsplan aktiv ist (oder die Anforderung fehlgeschlagen ist), nehmen Sie einen oder beide der folgenden Parameter auf:

      • --wait-for-state ACTIVE
      • --wait-for-state FAILED

      Beispiel:

      oci api-gateway usage-plan create --from-json file://gold-usageplan.json --wait-for-state ACTIVE

      Beachten Sie, dass Sie den Nutzungsplan erst verwenden können, wenn die Arbeitsanforderung ihn erfolgreich erstellt hat und der Nutzungsplan aktiv ist.

   3. (Optional) Um den Status des Nutzungsplans anzuzeigen, geben Sie Folgendes ein:

      oci api-gateway usage-plan get --usage-plan-id <usage-plan-ocid>

   4. (Optional) Um den Status der Anforderung anzuzeigen, die den Nutzungsplan erstellt:

      oci api-gateway work-request get --work-request-id <work-request-ocid>

   5. So zeigen Sie die Logs der Arbeitsanforderung an, die den Nutzungsplan erstellt:

      oci api-gateway work-request-log list --work-request-id <work-request-ocid>

   6. (Optional) Wenn die Arbeitsanforderung, die den Nutzungsplan erstellt, nicht erfolgreich ist und Sie die Fehlerlogs prüfen möchten, geben Sie Folgendes ein:

      oci api-gateway work-request-error --work-request-id <work-request-ocid>

   Weitere Informationen zur Verwendung der CLI finden Sie unter Befehlszeilenschnittstelle (CLI). Eine vollständige Liste der Flags und Optionen, die für CLI-Befehle verfügbar sind, finden Sie in der CLI-Hilfe.

Informationen zur Verwendung der API und zu Signieranforderungen finden Sie unter REST-API-Dokumentation und Sicherheitszugangsdaten. Informationen zu SDKs finden Sie unter SDKs und die CLI.

Verwenden Sie den Vorgang CreateUsagePlan, um einen Nutzungsplan zu erstellen.