Documentazione di Oracle Cloud Infrastructure

Creazione di un iscritto

Scopri come creare un sottoscrittore nell'ambito di una strategia per monitorare e gestire il numero di richieste inviate ai servizi backend con il gateway API.

I manager dei piani API possono creare sottoscrittori per i clienti (consumatori API) per specificare i piani di utilizzo che consentono loro di accedere alle API. Vedere Piani di utilizzo e abilitazioni, sottoscrittori e token client.

Una definizione di sottoscrittore include i nomi client e i token client per identificare in modo univoco i client API e specifica i piani di utilizzo che consentono loro di accedere alle API.

Nota:

  • Prima di poter creare un sottoscrittore, è necessario che esista già almeno uno dei piani di utilizzo a cui si desidera che il sottoscrittore effettui la sottoscrizione (vedere Creazione di un piano di utilizzo).
  • Se si definisce un sottoscrittore e si specificano più client API, il limite di frequenza e la quota nell'abilitazione di un piano di utilizzo vengono condivisi tra tutti i client API.
  • Dopo aver creato un sottoscrittore, è possibile aggiungere e rimuovere i client e modificare i token client.
  • Il token client specificato per un client API in una definizione di sottoscrittore è destinato solo a scopi di generazione report del piano di utilizzo. Non utilizzare questo token per l'autenticazione e l'autorizzazione del client API. In alternativa, utilizzare le funzioni del responsabile autorizzazioni o i token Web JSON (JWT) per l'autenticazione e l'autorizzazione del client API. Vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.
  • Se una distribuzione API viene visualizzata in più piani di utilizzo a cui è stato sottoscritto un sottoscrittore, per accedere alla distribuzione API viene utilizzato il primo piano di utilizzo nella lista dei piani di utilizzo sottoscritti. È possibile modificare l'ordine dell'elenco dei piani di utilizzo sottoscritti.
  • Se un sottoscrittore è sottoscritto a un piano di utilizzo e si desidera sottoscrivere il sottoscrittore a un nuovo piano di utilizzo, Oracle consiglia di eseguire l'operazione in due passi. Per iniziare, aggiungere il nuovo piano di utilizzo alla definizione del sottoscrittore come primo piano di utilizzo nell'elenco dei piani di utilizzo sottoscritti e salvare la modifica. Rimuovere quindi il piano di utilizzo precedente dall'elenco dei piani di utilizzo sottoscritti e salvare la modifica.
  • È possibile creare una definizione di sottoscrittore che inizialmente non dispone di client API e/o piani di utilizzo target, quindi aggiungerli in un secondo momento. Tenere presente che fino a quando non sono stati aggiunti sia i client API che i piani di utilizzo target a una definizione di sottoscrittore, il sottoscrittore non può accedere alle API.

È possibile creare un sottoscrittore mediante:

  • utilizzo di Console
  • uso dell'interfaccia CLI e di un file JSON

Utilizzo della console per creare un sottoscrittore

Per creare un nuovo sottoscrittore ed eseguirne la sottoscrizione a uno o più piani di utilizzo mediante la console, effettuare le operazioni riportate di seguito.

  1. Nella pagina di elenco Sottoscrittori, selezionare Crea sottoscrittore. Per informazioni su come trovare la pagina dell'elenco, vedere Elenco dei sottoscrittori.

  2. Specificare i valori riportati di seguito per il sottoscrittore.

    • Nome: il nome del nuovo sottoscrittore. Ad esempio, Premium-subscriber. Evitare di fornire informazioni riservate.
    • Compartimento: compartimento a cui appartiene il nuovo sottoscrittore.
    • Client: uno o più client API che accederanno alle distribuzioni API utilizzando i piani di utilizzo a cui il sottoscrittore è sottoscritto. Per ogni client API, specificare:
      • Nome: nome scelto per il client API. I nomi client devono essere univoci all'interno di un sottoscrittore. Ad esempio, android. Suggerimento: specificare un nome significativo perché potrebbe essere fornito ai consumer API ai fini della raccolta e dell'analisi dei dati del piano di utilizzo.
      • Token: stringa di caratteri scelta per identificare in modo univoco il client API. Il token specificato deve essere univoco all'interno della tenancy per l'area corrente e non deve superare i 128 caratteri. Ad esempio, abc123def456ghi789jkl. Se non esiste già alcun identificativo appropriato, selezionare Genera token per crearne uno.
        Nota

        Il token specificato per un client API in una definizione di sottoscrittore è destinato solo a scopi di generazione report del piano di utilizzo. Non utilizzare questo token per l'autenticazione e l'autorizzazione del client API. In alternativa, utilizzare le funzioni del responsabile autorizzazioni o i token Web JSON (JWT) per l'autenticazione e l'autorizzazione del client API. Vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.
    • Piani di utilizzo: selezionare Aggiungi piano di utilizzo per sottoscrivere il sottoscrittore a uno o più piani di utilizzo.
  3. Facoltativamente, selezionare Opzioni avanzate e specificare:
    • Tag: se si dispone delle autorizzazioni per creare una risorsa, si dispone anche delle autorizzazioni per applicare tag in formato libero a tale risorsa. Per applicare una tag defined, è necessario disporre delle autorizzazioni per utilizzare la tag namespace. Per ulteriori informazioni sull'applicazione di tag, vedere Tag risorsa. Se non sei sicuro di applicare i tag, salta questa opzione o chiedi a un amministratore. È possibile applicare le tag in un secondo momento.
  4. Selezionare Crea per creare il sottoscrittore.

    La creazione del nuovo sottoscrittore può richiedere alcuni minuti. Durante la creazione, il sottoscrittore viene visualizzato con lo stato Creazione nella pagina Piani di utilizzo. Una volta creato correttamente, il nuovo sottoscrittore viene visualizzato con lo stato Attivo.

    Inoltre, anziché creare immediatamente il nuovo sottoscrittore, è possibile crearlo in un secondo momento utilizzando Resource Manager e Terraform, selezionando Salva come stack per salvare la definizione della risorsa come configurazione Terraform. Per ulteriori informazioni sul salvataggio degli stack dalle definizioni delle risorse, vedere Creazione di uno stack da una pagina di creazione delle risorse.

  5. Se il sottoscrittore è stato visualizzato con stato Attivo per più di alcuni minuti (o se l'operazione di creazione del sottoscrittore non è riuscita):

    1. Selezionare il nome del sottoscrittore e selezionare Richieste di lavoro per visualizzare una panoramica dell'operazione di creazione del sottoscrittore.
    2. Selezionare l'operazione Crea sottoscrittore per visualizzare ulteriori informazioni sull'operazione, inclusi i messaggi di errore, i messaggi di log e lo stato delle risorse associate.
    3. Se l'operazione di creazione del sottoscrittore non è riuscita e non è possibile diagnosticare la causa del problema dalle informazioni sulla richiesta di lavoro, vedere Risoluzione dei problemi del gateway API.

Utilizzo dell'interfaccia CLI e di un file JSON per creare un sottoscrittore

Per creare un nuovo sottoscrittore ed eseguirne la sottoscrizione a uno o più piani di utilizzo mediante l'interfaccia CLI:

  1. Utilizzando l'editor JSON preferito, creare un file di definizione del sottoscrittore nel formato seguente:
    {
    "displayName": "<subscriber-name>",
    "clients": [
        {"name": "<api-client-name-one>", "token": "<unique-identifier>"}
    ],
    "usagePlans": ["<usage-plan-ocid>"],
    "compartmentId": "<compartment-ocid>",
    "freeformTags": {},
    "definedTags": {}
}
    dove:
    • "displayName": "<subscriber-name>" è il nome del nuovo abbonato. Ad esempio, "displayName": "Premium-subscriber". Evitare di inserire informazioni riservate.
    • "clients": [{...}] specifica uno o più client API che accederanno alle distribuzioni API utilizzando i piani di utilizzo a cui il sottoscrittore è sottoscritto. Per ogni client API, specificare:
      • "name": "<api-client-name>" è il nome scelto per il client API. I nomi client devono essere univoci all'interno di un sottoscrittore. Ad esempio, "name": "android". Suggerimento: specificare un nome significativo perché potrebbe essere fornito ai consumer API ai fini della raccolta e dell'analisi dei dati del piano di utilizzo. Evitare di inserire informazioni riservate.
      • "token": "<unique-identifier>" è una stringa di caratteri scelta per identificare in modo univoco il client API. Il token specificato deve essere univoco all'interno della tenancy per l'area corrente e non deve superare i 128 caratteri. Ad esempio, "token": "abc123def456ghi789jkl".
        Nota

        Il token specificato per un client API in una definizione di sottoscrittore è destinato solo a scopi di generazione report del piano di utilizzo. Non utilizzare questo token per l'autenticazione e l'autorizzazione del client API. In alternativa, utilizzare le funzioni del responsabile autorizzazioni o i token Web JSON (JWT) per l'autenticazione e l'autorizzazione del client API. Vedere Aggiunta di autenticazione e autorizzazione alle distribuzioni API.
    • "usagePlans": [{…}] specifica l'OCID di uno o più piani di utilizzo a cui sottoscrivere il sottoscrittore. Il piano di utilizzo può appartenere allo stesso compartimento del sottoscrittore, ma non è necessario. Ad esempio, "usagePlans": "ocid1.usageplan.oc1..aaaaaaaaab______gap".
    • "compartmentId": "<compartment-ocid>" è l'OCID del compartimento a cui appartiene il nuovo sottoscrittore. Ad esempio, "ocid1.compartment.oc1..aaaaaaaa7______ysq"

    Ad esempio:

    {
    "displayName": "MySubscriber",
    "clients": [
        {"name": "android", "token": "XXXXXX"},
        {"name": "iOS", "token": "YYYYYY"}
    ],
    "usagePlans": ["ocid1.usageplan.oc1..aaaaaaaaab______gap", "ocid1.usageplan.oc1..aaaaaaaaab______eya"],
    "compartmentId": "ocid1.compartment.oc1..aaaaaaaa7______ysq",
    "freeformTags": {},
    "definedTags": {}
}
  2. Salvare il file di definizione del sottoscrittore con il nome desiderato. Ad esempio, premium-subscriber.json
  3. Utilizzare il file di definizione del sottoscrittore per creare un sottoscrittore utilizzando l'interfaccia CLI:
    1. Configurare l'ambiente client per l'uso dell'interfaccia CLI (Configuring Your Client Environment to use the CLI for API Gateway Development).

    2. Aprire un prompt dei comandi ed eseguire oci api-gateway subscriber create per creare il sottoscrittore dal file di definizione del sottoscrittore:

      oci api-gateway subscriber create --from-json file://<subscriber-definition>.json

      dove:

      • --from-json file://<subscriber-definition>.json è il file che contiene la definizione dell'abbonato, incluso un percorso.

      Ad esempio:

      oci api-gateway subscriber create --from-json file://premium-subscriber.json

      La risposta al comando include quanto riportato di seguito.

      • L'OCID del sottoscrittore e altri dettagli.
      • Stato del ciclo di vita (ad esempio, ACTIVE, FAILED).
      • ID della richiesta di lavoro per creare il sottoscrittore (i dettagli delle richieste di lavoro sono disponibili per sette giorni dopo il completamento, l'annullamento o l'errore).

      Se si desidera che il comando attenda la restituzione del controllo fino a quando il sottoscrittore non è attivo (o la richiesta non è riuscita), includere uno o entrambi i seguenti parametri:

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

      Ad esempio:

      oci api-gateway subscriber create --from-json file://premium-subscriber.json --wait-for-state ACTIVE

      Tenere presente che non è possibile utilizzare il sottoscrittore finché la richiesta di lavoro non l'ha creata correttamente e il sottoscrittore non è attivo.

    3. (Facoltativo) Per visualizzare lo stato del sottoscrittore, immettere:

      oci api-gateway subscriber get --subscriber-id <subscriber-ocid>

    4. (Facoltativo) Per visualizzare lo stato della richiesta di lavoro che sta creando il sottoscrittore, immettere:

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

    5. (Facoltativo) Per visualizzare i log della richiesta di lavoro che sta creando il sottoscrittore, immettere:

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

    6. (Facoltativo) Se la richiesta di lavoro che sta creando il sottoscrittore non riesce e si desidera esaminare i log degli errori, immettere:

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

    Per ulteriori informazioni sull'uso dell'interfaccia CLI, vedere Command Line Interface (CLI, interfaccia a riga di comando). Per un elenco completo dei flag e delle opzioni disponibili per i comandi della CLI, vedere la Guida della CLI.