Pubblicazione delle API

Questa pagina si applica ad Apigee e Apigee hybrid.

Visualizza la documentazione di Apigee Edge.

Pubblica le API sul tuo portale per renderle disponibili per l'utilizzo da parte degli sviluppatori di app, come descritto nelle sezioni seguenti.

Panoramica della pubblicazione di API

Il processo di pubblicazione delle API nel portale è suddiviso in due passaggi:

  1. Seleziona il prodotto API che vuoi pubblicare nel tuo portale.
  2. Esegui il rendering della documentazione di riferimento dell'API dal documento OpenAPI o dallo schema GraphQL per consentire agli sviluppatori di app di conoscere le tue API. Per maggiori informazioni, consulta Informazioni sulla documentazione dell'API.

Cosa viene pubblicato sul portale?

Quando pubblichi un'API, al tuo portale vengono apportati automaticamente i seguenti aggiornamenti:

  • Documentazione di riferimento dell'API. L'interfaccia fornita dipende se pubblichi l'API utilizzando un documento OpenAPI o uno schema GraphQL. Vedi:
  • Un link alla pagina di riferimento dell'API viene aggiunto alla pagina API

    La pagina API (inclusa nel portale di esempio) fornisce un elenco di tutte le API pubblicate nel tuo portale, in ordine alfabetico, con link alla documentazione di riferimento delle rispettive API per maggiori informazioni. (Facoltativo) Puoi personalizzare quanto segue:

    • Immagine visualizzata per ogni scheda API
    • Categorie utilizzate per taggare le API e consentire agli sviluppatori di scoprire le API correlate nella pagina API
    Pagina delle API nel portale live che mostra due categorie e l'utilizzo delle immagini Pagina delle API nel portale live che mostra due categorie e l'utilizzo delle immagini

SmartDocs (OpenAPI)

Quando pubblichi un'API utilizzando un documento OpenAPI, la documentazione di riferimento dell'API SmartDocs viene aggiunta al tuo portale.

Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il riquadro Prova questa API per effettuare una richiesta API e visualizzare l'output. Prova questa API funziona con endpoint non protetti o protetti utilizzando l'autenticazione di base, con chiave API o OAuth, in base al metodo di sicurezza definito nel documento OpenAPI. Per OAuth, sono supportati i seguenti flussi: codice di autorizzazione, password e credenziali client.

Pagina della documentazione di riferimento dell'API con callout che mostrano come autorizzare la chiamata API, sganciare il riquadro Prova questa API, scaricare la specifica pertinente ed eseguire l'API.

Pagina della documentazione di riferimento dell'API con callout che mostrano come autorizzare la chiamata API, sganciare il riquadro Prova questa API, scaricare la specifica pertinente ed eseguire l'API.

Fai clic su A schermo intero per espandere il riquadro Prova questa API. Il riquadro espanso ti consente di visualizzare la chiamata curl e gli esempi di codice in vari formati, come HTTP, Python, Node.js e altri, come mostrato di seguito.

Riquadro Prova questa API espanso

Riquadro Prova questa API espanso

GraphQL Explorer

Quando pubblichi un'API utilizzando uno schema GraphQL, Explorer GraphQL viene aggiunto al tuo portale. GraphQL Explorer è un ambiente di prova interattivo per eseguire query sull'API. L'explorer si basa su GraphiQL, un'implementazione di riferimento dell'IDE GraphQL sviluppata dalla GraphQL Foundation.

Gli sviluppatori possono utilizzare GraphQL Explorer per esplorare la documentazione interattiva basata sullo schema, creare ed eseguire query, visualizzare i risultati delle query e scaricare lo schema. Per proteggere l'accesso all'API, gli sviluppatori possono trasmettere le intestazioni di autorizzazione nel riquadro Intestazioni richiesta. Per ulteriori informazioni su GraphQL, visita il sito graphql.org.

GraphQL Explorer nel portale

GraphQL Explorer nel portale

Informazioni sulla documentazione dell'API

Ogni documento OpenAPI o GraphQL funge da fonte attendibile durante l'intero ciclo di vita di un'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita dell'API, dallo sviluppo alla pubblicazione al monitoraggio. Quando modifichi un documento, devi essere consapevole dell'impatto che le modifiche hanno sulla tua API nelle altre fasi del ciclo di vita, come descritto in Cosa succede se modifico un documento?

Quando pubblichi l'API in un portale, salvi una versione del documento OpenAPI o GraphQL per eseguire il rendering della documentazione di riferimento dell'API. Se modifichi il documento, potresti decidere di aggiornare la documentazione di riferimento dell'API pubblicata sul portale per riflettere le ultime modifiche.

Informazioni sugli URL di callback

Se le tue app richiedono un URL di callback, ad esempio quando utilizzi il tipo di concessione del codice di autorizzazione OAuth 2.0 (spesso chiamato OAuth a tre passaggi), puoi richiedere agli sviluppatori di specificare un URL di callback quando registrano le loro app. L'URL di callback in genere specifica l'URL di un'app designata per ricevere un codice di autorizzazione per conto dell'app client. Per ulteriori informazioni, consulta Implementazione del tipo di concessione del codice di autorizzazione.

Puoi configurare se richiedere o meno un URL di callback durante la registrazione dell'app quando aggiungi un'API al portale. Puoi modificare questa impostazione in qualsiasi momento, come descritto in Gestire l'URL di callback per un'API.

Quando registrano un'app, gli sviluppatori devono inserire un URL di callback per tutte le API che lo richiedono, come descritto in Registrazione di app.

Configurare il proxy API per supportare il riquadro Prova questa API

Prima di pubblicare le tue API utilizzando un documento OpenAPI, devi configurare il proxy API per supportare l'invio di richieste nel riquadro Prova questa API nella documentazione di riferimento dell'API Smart Docs, nel seguente modo:

  • Aggiungi il supporto CORS ai proxy API per applicare le richieste multiorigine lato client.
    CORS è un meccanismo standard che consente alle chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web di interagire con risorse di domini non di origine. CORS è una soluzione comunemente implementata per i criteri della stessa origine applicati da tutti i browser.
  • Aggiorna la configurazione del proxy API se utilizzi l'autenticazione di base o OAuth 2.0.

La tabella seguente riassume i requisiti di configurazione del proxy API per supportare il riquadro Prova questa API nella documentazione di riferimento dell'API SmartDocs in base all'accesso di autenticazione.

Accesso Auth Requisiti di configurazione delle policy
Nessuna o chiave API Aggiungi il supporto CORS al proxy API seguendo i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
Autenticazione di base Esegui i seguenti passaggi:
  1. Aggiungi il supporto CORS al proxy API seguendo i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
  2. In Aggiungi policy CORS, assicurati che l'intestazione Access-Control-Allow-Headers includa l'attributo authorization. Ad esempio: 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
OAuth 2.0
  1. Aggiungi il supporto CORS al proxy API seguendo i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
  2. In Aggiungi policy CORS, assicurati che l'intestazione Access-Control-Allow-Headers includa l'attributo authorization. Ad esempio: 
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
  3. Correggi il comportamento non conforme alla RFC nei tuoi criteri OAuth 2.0. Per comodità, utilizza la soluzione OAuth 2.0 di esempio fornita su GitHub o esegui i seguenti passaggi:
    • Assicurati che l'elemento <GrantType> nel criterio OAuth 2.0 sia impostato su request.formparam.grant_type (parametro del modulo). Per ulteriori informazioni, vedi <GrantType>.
    • Assicurati che token_type nella policy OAuth 2.0 sia impostato su Bearer e non sul valore predefinito BearerToken.

Gestione delle API

Gestisci le tue API come descritto nelle sezioni seguenti.

Esplora API

Utilizza la console o il comando curl per visualizzare le API presenti nel tuo portale.

Per visualizzare il catalogo delle API:

Console

UI di Cloud Console

  1. Nella console Apigee in Cloud, vai alla pagina Distribuzione > Portali.

    Vai a Portali

  2. Fai clic sul portale.

  3. Fai clic su Catalogo API.

  4. Fai clic sulla scheda API. Viene visualizzato un elenco delle API aggiunte al tuo portale.

UI classica

  1. Seleziona Pubblica > Portali e seleziona il tuo portale.

  2. Fai clic su Catalogo API nella home page del portale.
    In alternativa, puoi selezionare Catalogo API nel menu a discesa del portale nel menu di navigazione in alto.
    La scheda API nel catalogo API mostra un elenco delle API che sono state aggiunte al tuo portale.

    Scheda API che mostra informazioni sulle API, tra cui nome, descrizione, visibilità, categorie, specifica associata e data di modifica

    Scheda API che mostra informazioni sulle API, tra cui nome, descrizione, visibilità, categorie, specifica associata e data di modifica

La scheda API ti consente di:

curl

Per elencare le API utilizzando organizations.sites.apidocs/list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

Consulta Note sulla paginazione per istruzioni sull'utilizzo della paginazione nel payload della risposta.

Payload della risposta:

{
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ],
  "nextPageToken": ""
}

Dove:

  • modified: Ora dell'ultima modifica dell'elemento del catalogo in millisecondi dal periodo. Ad esempio, 1698165480000.
  • id: L'ID dell'articolo del catalogo. Ad esempio, 399668.

Note sulla paginazione:

  • Dimensioni pagina:utilizza pageSize per specificare il numero di elementi dell'elenco da restituire in una pagina. Il valore predefinito è 25 e il valore massimo è 100. Se sono presenti pagine aggiuntive, nextPageToken viene compilato con un token:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE" \
   -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Sostituisci:

    • PAGE_SIZE con il numero di elementi dell'elenco da restituire in una pagina. Ad esempio, 10.

    Payload della risposta:

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "918815495",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "apigee",
      "modified": "1699146887000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    }
  ],
  "nextPageToken": "7zcqrin9l6xhi4nbrb9"
}

  • Token pagina:

    Utilizza pageToken per recuperare le pagine successive quando ce n'è più di una:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs?pageSize=PAGE_SIZE&pageToken=PAGE_TOKEN" \
      -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Sostituisci:

    • PAGE_SIZE con il numero di elementi dell'elenco da restituire in una pagina. Ad esempio, 10.
    • PAGE_TOKEN con il valore nextPageToken. Ad esempio: 7zcqrin9l6xhi4nbrb9.

Aggiungi un'API

Per aggiungere un'API al tuo portale:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.

  3. Aggiungi un'API.

    UI di Cloud Console

    1. Fai clic su + API. Viene visualizzata la finestra di dialogo Aggiungi un'API.
    2. Seleziona il prodotto API che vuoi aggiungere al portale.

    UI classica

    1. Fai clic su Aggiungi.

      Viene visualizzata la finestra di dialogo Aggiungi un prodotto API al catalogo.

    2. Seleziona il prodotto API che vuoi aggiungere al portale.

    3. Fai clic su Avanti. Viene visualizzata la pagina Dettagli API.

  4. Configura i contenuti della documentazione di riferimento dell'API e la relativa visibilità sul portale:

    Campo Descrizione
    Pubblicato Seleziona Pubblicato per pubblicare l'API nel portale. Deseleziona la casella di controllo se non vuoi pubblicare l'API. Puoi modificare l'impostazione in un secondo momento, come descritto nella sezione Pubblicare o annullare la pubblicazione di un'API.
    Mostra titolo Aggiorna il titolo dell'API visualizzato nel catalogo. Per impostazione predefinita, viene utilizzato il nome del prodotto API. Puoi modificare il titolo visualizzato in un secondo momento, come descritto in Modificare il titolo e la descrizione visualizzati.
    Mostra descrizione Aggiorna la descrizione dell'API visualizzata nel catalogo. Per impostazione predefinita, viene utilizzata la descrizione del prodotto API. Puoi modificare la descrizione visualizzata in un secondo momento, come descritto in Modificare il titolo e la descrizione visualizzati.
    Richiedi agli sviluppatori di specificare un URL di callback Attiva questa opzione se vuoi richiedere agli sviluppatori di app di specificare un URL di callback. Puoi aggiungere o aggiornare l'URL di callback in un secondo momento, come descritto in Gestire l'URL di callback per un'API.
    Documentazione dell'API

    Per utilizzare un documento OpenAPI:

    UI di Cloud Console

    1. Seleziona Documento OpenAPI.
    2. Fai clic su Seleziona.
    3. Esegui uno dei seguenti passaggi:
      • Fai clic sulla scheda Carica e carica un file.
      • Fai clic sulla scheda URL e importa una specifica fornendo un nome e un URL da cui importare.
    4. Fai clic su Seleziona.

    UI classica

    1. Seleziona Documento OpenAPI.
    2. Fai clic su Seleziona documento.
    3. Esegui uno dei seguenti passaggi:
      • Fai clic sulla scheda Carica file e carica un file.
      • Fai clic sulla scheda Importa da un URL e importa una specifica fornendo un nome e un URL da cui importare.
    4. Fai clic su Seleziona.

    Per utilizzare uno schema GraphQL:

    UI di Cloud Console

    1. Seleziona Schema GraphQL.
    2. Fai clic su Seleziona.
    3. Vai allo schema GraphQL e selezionalo.
    4. Specifica l'URL dell'endpoint, ovvero l'URI dell'endpoint GraphQL da interrogare dai consumer API.
    5. Fai clic su Seleziona.

    UI classica

    1. Seleziona Schema GraphQL.
    2. Fai clic su Seleziona documento.
    3. Vai allo schema GraphQL e selezionalo.
    4. Fai clic su Apri.
    5. Specifica l'URL dell'endpoint, ovvero l'URI dell'endpoint GraphQL da interrogare dai consumer API.
    6. Fai clic su Salva.

    In alternativa, puoi selezionare Nessuna documentazione e aggiungerne una in un secondo momento dopo l'aggiunta dell'API, come descritto in Gestire la documentazione dell'API.

    Visibilità

    Se non hai eseguito la registrazione alla release di anteprima della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni:

    • Utenti anonimi per consentire a tutti gli utenti di visualizzare l'API.
    • Utenti registrati per consentire solo agli utenti registrati di visualizzare l'API.

    Se hai eseguito la registrazione alla release di anteprima della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni:

    • Pubblico (visibile a tutti) per consentire a tutti gli utenti di visualizzare l'API.
    • Utenti autenticati per consentire solo agli utenti registrati di visualizzare l'API.
    • Segmenti di pubblico selezionati per selezionare i segmenti di pubblico specifici che vuoi che possano visualizzare l'API.

    Puoi gestire la visibilità del pubblico in un secondo momento, come descritto in Gestire la visibilità di un'API.

    Visualizza immagine Per visualizzare un'immagine sulla scheda API nella pagina API, fai clic su Seleziona immagine. Nella finestra di dialogo Seleziona immagine, seleziona un'immagine esistente, carica una nuova immagine o fornisci l'URL di un'immagine esterna e fai clic su Seleziona. Visualizza l'anteprima della miniatura dell'API e fai clic su Seleziona. Puoi aggiungere un'immagine in un secondo momento, come descritto in Gestire l'immagine di una scheda API. Quando specifichi l'URL di un'immagine esterna, questa non verrà caricata nei tuoi asset. Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme di sicurezza dei contenuti.
    Categorie

    Aggiungi le categorie con cui verrà taggata l'API per consentire agli sviluppatori di app di scoprire le API correlate nella pagina API. Per identificare una categoria:

    • Seleziona una categoria dall'elenco a discesa.
    • Aggiungi una nuova categoria come descritto in Aggiungere una categoria. La nuova categoria viene aggiunta alla pagina Categorie e resa disponibile quando aggiungi o modifichi altre API.

  5. Fai clic su Salva.

curl

Per aggiungere un'API al portale utilizzando organizations.sites.apidocs.create:

curl -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
         -H "Authorization: Bearer $(gcloud auth print-access-token)" \
         -H "Content-Type: application/json" \
         -d '{
            "title": "TITLE",
            "description": "DESCRIPTION",
            "anonAllowed": ANON_TRUE_OR_FALSE,
            "imageUrl": "IMAGE_URL",
            "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
            "categoryIds": [
              "CATEGORY_ID1",
              "CATEGORY_ID2"
            ],
            "published": PUBLISHED_TRUE_OR_FALSE,
            "apiProductName": "API_PRODUCT",
         }'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • TITLE con il titolo visualizzato. Ad esempio, Hello World 2.
  • DESCRIPTION con la descrizione del display. Ad esempio, Simple hello world example.
  • ANON_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true consente l'accesso degli utenti anonimi. Questa impostazione viene ignorata se hai eseguito la registrazione all'anteprima della funzionalità di gestione dei segmenti di pubblico.
  • IMAGE_URL con l'URL di un'immagine esterna utilizzata per l'articolo del catalogo o un percorso file per i file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, questa non viene caricata negli asset. Inoltre,il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme di sicurezza dei contenuti.
  • CALLBACK_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true richiede a un utente del portale di inserire un URL durante la gestione dell'app.

  • CATEGORY_ID: l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa più ID categoria con una virgola. Recupera l'ID categoria con il comando list API categories.

  • PUBLISHED_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true indica che l'API è disponibile pubblicamente.

  • API_PRODUCT con il nome del prodotto API. Ad esempio, Hello World 2.

Payload della risposta:

{
  "status": "success",
  "message": "API created",
  "requestId": "1662161889",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "modified": "1698948807000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "409405",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

Dove:

  • modified: Ora dell'ultima modifica dell'elemento del catalogo in millisecondi dal periodo. Ad esempio, 1698165480000.
  • id: L'ID dell'articolo del catalogo. Ad esempio, 399668.

Modificare un'API

Dopo aver aggiunto un'API, utilizza la console o una chiamata API per apportare modifiche.

Questa sezione fornisce un esempio dettagliato dei passaggi da seguire per modificare un'API esistente nel tuo portale.

Per impostazioni di modifica specifiche, consulta le sezioni successive.

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Apporta le modifiche che preferisci. Consulta le descrizioni delle opzioni in Aggiungere un'API.
  6. Fai clic su Salva.

curl

Dopo aver aggiunto un'API, utilizza la chiamata organizations.sites.apidocs.update per apportare modifiche.

Questo esempio illustra i passaggi necessari per modificare lo stato di pubblicazione dell'API nel portale da true a false. Se necessario, puoi modificare più di un'impostazione in una sola chiamata API.

  1. Recupera un elenco delle API nel tuo portale utilizzando organizations.sites.apidocs/list per individuare l'id generato che identifica in modo univoco ogni API:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Sostituisci quanto segue:

    • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
    • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

    Payload della risposta:

    {
  "status": "success",
  "message": "one page of apidocs returned",
  "requestId": "1167960478",
  "data": [
    {
      "siteId": "my-org-myportal",
      "title": "Hello New World",
      "description": "Simple hello new world example",
      "specId": "hellowworld",
      "modified": "1695841621000",
      "anonAllowed": true,
      "imageUrl": "/files/camper1.jpg?v=1695841491415",
      "id": "381054",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello New World"
    },
    {
      "siteId": "my-org-myportal",
      "title": "mock-product",
      "description": "Mock product",
      "specId": "apigee spec",
      "modified": "1698956849000",
      "anonAllowed": true,
      "id": "399638",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
      ],
      "published": true,
      "apiProductName": "mock-product"
    },
    {
      "siteId": "my-org-myportal",
      "title": "Hello World 2",
      "description": "Simple hello world example",
      "specId": "hello-new-world",
      "modified": "1698950207000",
      "anonAllowed": true,
      "imageUrl": "/files/book-tree.jpg?v=1698165437881",
      "id": "399668",
      "categoryIds": [
        "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
        "61c1014c-89c9-40e6-be3c-69cca3505620"
      ],
      "published": true,
      "apiProductName": "Hello World 2"
    }
  ]
}

    Dove:

    • modified: Ora dell'ultima modifica dell'elemento del catalogo in millisecondi dal periodo. Ad esempio, 1698165480000.
    • id: L'ID dell'articolo del catalogo. Ad esempio, 399668.

  2. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali per un'API specifica:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

    Sostituisci quanto segue:

    • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
    • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
    • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.

    Payload della risposta:

    {
  "status": "success",
  "message": "apidoc returned",
  "requestId": "2072952505",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example",
    "specId": "hello-new-world",
    "modified": "1698950207000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg?v=1698165437881",
    "id": "399668",
    "categoryIds": [
      "e0518597-ece2-4d7d-ba7c-d1793df0f8db",
      "61c1014c-89c9-40e6-be3c-69cca3505620"
    ],
    "published": true,
    "apiProductName": "Hello World 2"
  }
}

  3. Includi i valori modificabili che vuoi conservare nella chiamata organizations.sites.apidocs.update e modifica i valori che vuoi cambiare. Se ometti una riga, viene utilizzata l'impostazione predefinita. Per questo esempio, modifica l'impostazione published da true a false:

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": "IMAGE_URL",
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": false,
        "apiProductName": "API_PRODUCT",
     }'

    Sostituisci quanto segue:

    • TITLE con il titolo visualizzato. Ad esempio, Hello World 2.
    • DESCRIPTION con la descrizione del display. Ad esempio, Simple hello world example.
    • ANON_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true consente l'accesso degli utenti anonimi. Questa impostazione viene ignorata se hai eseguito la registrazione all'anteprima della funzionalità di gestione dei segmenti di pubblico.
    • IMAGE_URL con l'URL di un'immagine esterna utilizzata per l'articolo del catalogo o un percorso file per i file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, questa non viene caricata negli asset. Inoltre,il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme di sicurezza dei contenuti.
    • CALLBACK_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true richiede a un utente del portale di inserire un URL durante la gestione dell'app.
    • CATEGORY_ID: l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa più ID categoria con una virgola. Recupera l'ID categoria con il comando list API categories.
    • API_PRODUCT con il nome del prodotto API. Ad esempio, Hello World 2.

    Payload della risposta:

    {
  "status": "success",
  "message": "ApiDoc updated",
  "requestId": "197181831",
  "data": {
    "siteId": "my-org-myportal",
    "title": "Hello World 2",
    "description": "Simple hello world example.",
    "modified": "1698884328000",
    "anonAllowed": true,
    "imageUrl": "/files/book-tree.jpg",
    "id": "408567",
    "requireCallbackUrl": true,
    "categoryIds": [
      "88fbfd1d-9300-49f7-bfc2-531ade4c63d4",
      "630c4cf9-109a-48b0-98cc-ef4c12ae4474"
    ],
    "published": PUBLISHED_TRUE_OR_FALSE,
    "apiProductName": "Hello World 2"
  }
}

Pubblicare o annullare la pubblicazione di un'API

La pubblicazione è il processo che rende le tue API disponibili per l'utilizzo da parte degli sviluppatori di app.

Per pubblicare o annullare la pubblicazione di un'API sul tuo portale:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Seleziona o deseleziona Pubblicata (elencata nel catalogo) per pubblicare o annullare la pubblicazione dell'API sul tuo portale, rispettivamente.
  6. Fai clic su Salva.

curl

Includi uno dei seguenti elementi nella chiamata update:

  "published": true,    # API is published to your portal
  "published": false,   # API is not published in your portal

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Gestire la visibilità di un'API

Gestisci la visibilità di un'API nel tuo portale consentendo l'accesso a:

Per gestire la visibilità di un'API nel tuo portale:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

  5. Seleziona l'impostazione di visibilità. Se hai eseguito la registrazione alla release di anteprima della funzionalità dei segmenti di pubblico, seleziona una delle seguenti opzioni in Visibilità API:

    • Pubblica (visibile a chiunque) per consentire a tutti gli utenti di visualizzare la pagina.
    • Utenti autenticati per consentire la visualizzazione della pagina solo agli utenti registrati.
    • Segmenti di pubblico selezionati per selezionare i segmenti di pubblico specifici che vuoi che possano visualizzare la pagina. Vedi Gestire i segmenti di pubblico per il portale.

    In caso contrario, seleziona una delle seguenti opzioni in Pubblico:

    • Utenti anonimi per consentire a tutti gli utenti di visualizzare la pagina.
    • Utenti registrati per consentire la visualizzazione della pagina solo agli utenti registrati.

  6. Fai clic su Salva.

curl

Se hai eseguito la registrazione alla release di anteprima della funzionalità di gestione dei segmenti di pubblico, utilizza la console per gestire i segmenti di pubblico.

Se non hai eseguito la registrazione alla funzionalità di gestione dei segmenti di pubblico, la visibilità viene gestita utilizzando anonAllowed.

Includi uno dei seguenti elementi nella chiamata update:

  # When not enrolled in the Preview release of the audience management feature:

  "anonAllowed": true,      # Anonymous users can see the API
  "anonAllowed": false,     # Only registered users can see the API

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Gestisci l'URL di callback per un'API

Gestisci l'URL di callback per un'API. Vedi Informazioni sugli URL di callback.

Per gestire l'URL di callback per un'API:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Seleziona o deseleziona Richiedi agli sviluppatori di specificare un URL di callback per specificare se un URL di callback è obbligatorio o meno.
  6. Fai clic su Salva.

curl

Includi uno dei seguenti elementi nella chiamata update:

  "requireCallbackUrl": true,    # Portal user is required to input a URL
  "requireCallbackUrl": false,   # Portal user is not required to input a URL

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Gestire l'immagine di una scheda API

Gestisci l'immagine visualizzata con una scheda API nella pagina API aggiungendo o modificando l'immagine corrente.

Per gestire l'immagine di una scheda API:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

  5. Individua e seleziona un'immagine:

    UI di Cloud Console

    • Fai clic su Seleziona per specificare un'immagine.
    • Fai clic sulla x per rimuovere l'immagine.

    UI classica

    • Fai clic su Seleziona immagine per specificare un'immagine se non ne è stata selezionata nessuna.
    • Fai clic su Cambia immagine per specificare un'immagine diversa.
    • Fai clic sulla x nell'immagine per rimuoverla.

    Quando specifichi un'immagine, specifica un'immagine con un URL esterno utilizzato per l'elemento del catalogo o un percorso file per i file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, questa non viene caricata nelle tue risorse. Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme di sicurezza dei contenuti.

  6. Fai clic su Salva.

curl

Includi quanto segue nella chiamata update:

  # Omit line for no image file

  "imageUrl": "IMAGE_URL"    # URL of the external image or name of the image file

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Tagga un'API utilizzando le categorie

L'utilizzo delle categorie aiuta gli sviluppatori di app a scoprire le API correlate. Vedi anche Gestire le categorie.

Per taggare un'API con categorie:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

  5. Specifica una categoria.

    UI di Cloud Console

    1. Seleziona una o più categorie dall'elenco a discesa Categorie. Se non sono presenti categorie, consulta la sezione Gestisci categorie.
    2. Fai clic su OK.

    UI classica

    1. Fai clic nel campo Categorie ed esegui uno dei seguenti passaggi:
      • Seleziona una categoria dall'elenco a discesa.
      • Aggiungi una nuova categoria digitandone il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile quando aggiungi o modifichi altre API.
    2. Ripeti l'operazione per taggare l'API con altre categorie.

  6. Fai clic su Salva.

curl

Includi quanto segue nella chiamata update:

  # Omit line for no categories

  "categoryIds": [
      "CATEGORY_ID1",      # A category ID number
      "CATEGORY_ID2"       # A category ID number
    ],

Utilizza il comando elenca categorie per ottenere i numeri ID delle categorie.

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Modificare il titolo e la descrizione visualizzati

Per modificare il titolo e la descrizione visualizzati:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Modifica i campi Titolo visualizzato e Descrizione visualizzata, se necessario.
  6. Fai clic su Salva.

curl

Includi quanto segue nella chiamata update:

  "title": "TITLE",              # Display title
  "description": "DESCRIPTION",  # Display description

Per modificare l'API:

  1. Utilizza la chiamata organizations.sites.apidocs.get per restituire i valori attuali:

    curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)"

  2. Utilizza la chiamata organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli che vuoi cambiare. Se ometti un'impostazione modificabile, viene utilizzato il valore predefinito.

    curl -X PUT "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
     -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" \
     -d '{
        "title": "TITLE",
        "description": "DESCRIPTION",
        "anonAllowed": ANON_TRUE_OR_FALSE,
        "imageUrl": IMAGE_URL,
        "requireCallbackUrl": CALLBACK_TRUE_OR_FALSE,
        "categoryIds": [
          "CATEGORY_ID1",
          "CATEGORY_ID2"
        ],
        "published": PUBLISHED_TRUE_OR_FALSE,
        "apiProductName": "API_PRODUCT",
     }'

Consulta Modificare un'API per un esempio dettagliato dei passaggi, delle variabili e del payload restituito.

Rimuovere un'API

Per rimuovere un'API dal portale:

Console

  1. Accedere al catalogo delle API.
  2. Seleziona la scheda API, se non è già selezionata.

  3. Elimina l'API.

    UI di Cloud Console

    Fai clic su Altro > Elimina.

    UI classica

    1. Posiziona il cursore sull'API nell'elenco per visualizzare il menu delle azioni.
    2. Fai clic su Elimina.

  4. Fai clic su Elimina per confermare.

curl

Per rimuovere un'API dal portale utilizzando organizations.sites.apidocs.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.

Payload della risposta:

{
  "status":"success",
  "message":"Apidoc deleted",
  "requestId":"645138256"
}

Gestire la documentazione dell'API

Le sezioni seguenti descrivono come aggiornare, scaricare o rimuovere la documentazione API.

Aggiornare la documentazione dell'API

Dopo aver pubblicato l'API, puoi caricare in qualsiasi momento una nuova versione del documento OpenAPI o GraphQL.

Per caricare una versione diversa della documentazione dell'API:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Per la documentazione dell'API, seleziona una delle seguenti opzioni:
    • Documento OpenAPI
    • Schema GraphQL

  6. Individua il file.

    UI di Cloud Console

    1. Fai clic su Seleziona.
    2. Individua e seleziona il file.

    UI classica

    1. Fai clic su Seleziona documento e seleziona l'ultima versione del documento.

  7. Per GraphQL, specifica l'URL dell'endpoint.

  8. Fai clic su Seleziona.

  9. Fai clic su Salva.

curl

Per aggiornare i contenuti della documentazione OpenAPI o GraphQL utilizzando organizations.sites.apidocs.updateDocumentation:

OpenAPI

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"oasDocumentation": {
           "spec":{ "displayName":"DISPLAY_NAME",
                    "contents":"CONTENTS"}
            }
        }'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.
  • DISPLAY_NAME con il nome visualizzato della documentazione dell'API. Ad esempio, Hello World 2.
  • CONTENTS con la stringa codificata in base64 dei contenuti della documentazione dell'API. La maggior parte degli ambienti di sviluppo contiene un'utilità di conversione base64 oppure esistono molti strumenti di conversione online.

Payload della risposta:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
 "data": {
   "oasDocumentation": {
     "spec": {
        "displayName": "Hello World 2"
      },
     "Format": "YAML"
   }
 }
}

GraphQL

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d '{"graphqlDocumentation": {
         "schema":{"displayName":"DISPLAY_NAME",
         "contents":"CONTENTS"},
         "endpointUri": "ENDPOINT_URI"
          }
      }'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.
  • DISPLAY_NAME con il nome visualizzato della documentazione dell'API. Ad esempio, Hello World 2.
  • ENDPOINT_URI con il nome di dominio dell'URI dell'endpoint. Ad esempio, https://demo.google.com/graphql.
  • CONTENTS con la stringa codificata in base64 dei contenuti della documentazione dell'API. La maggior parte degli ambienti di sviluppo contiene un'utilità di conversione base64 oppure esistono molti strumenti di conversione online.

Payload della risposta:

{
 "status":"success",
 "message":"Api documentation updated",
 "requestId":"645138278"
  "data": {
    "graphqlDocumentation": {
      "schema": {
        "displayName": "Hello World 2"
      },
     "endpointUri": "https://demo.google.com/graphql"
    }
  }
}

La documentazione di riferimento dell'API viene visualizzata dal documento e aggiunta alla pagina API del portale live.

Scaricare la documentazione dell'API

Dopo aver pubblicato l'API, puoi scaricare in qualsiasi momento la documentazione di riferimento OpenAPI o GraphQL pubblicata sul tuo portale.

Per scaricare la documentazione dell'API utilizzando organizations.sites.apidocs.getDocumentation:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

  • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.

    Payload della risposta:

{
  "status":"success",
  "message":"Api documentation downloaded",
  "requestId":"645138256",
  "data": {
      "oasDocumentation":{
          "spec":{
            "displayName":"Hello World 2",
            "contents":"c3dhZ2dlcjogJzIuMCcKaW5mbzoKICBkZXNlI ..."
          },
          "Format": YAML
      }
  }
}

Dove:

contents: La stringa con codifica base64 dei contenuti della documentazione dell'API.

Rimuovere la documentazione dell'API

Per rimuovere la documentazione dell'API:

Console

  1. Accedere al catalogo delle API.
  2. Se non è già selezionata, fai clic sulla scheda API.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Per la documentazione dell'API, seleziona Nessuna documentazione.
  6. Fai clic su Salva.

curl

Per rimuovere i contenuti dei documenti API utilizzando un'API, cancella le impostazioni esistenti inviando un corpo della richiesta vuoto.

Per inviare un corpo della richiesta vuoto e cancellare i contenuti esistenti utilizzando organizations.sites.apidocs.updateDocumentation:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apidocs/API_DOC/documentation" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{}'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il id generato del documento. Ad esempio 399668. Utilizza il comando list API docs per trovare questo valore.

Payload della risposta:

{
   "status":"success",
   "message":"Api documentation updated",
   "requestId":"645138279"
}

Gestisci categorie

Tagga un'API utilizzando le categorie per consentire agli sviluppatori di app di scoprire le API correlate nella pagina API del portale live. Aggiungi e gestisci le categorie, come descritto nelle sezioni seguenti.

Esplorare le categorie

Utilizza la console o il comando curl per visualizzare le categorie.

Console

  1. Vai alla pagina Portali.

    UI di Cloud Console

    1. Nella console Apigee in Cloud, vai alla pagina Distribuzione > Portali.

      Vai a Portali

    2. Fai clic sul portale.

    UI classica

    1. Seleziona Pubblica > Portali e seleziona il tuo portale.

  2. Fai clic su Catalogo API.

  3. Fai clic sulla scheda Categorie. La scheda Categorie nel catalogo API mostra l'elenco delle categorie che sono state definite per il tuo portale. La pagina API ti consente di

curl

Per elencare le categorie utilizzando organizations.sites.apicategories.list:

curl -X GET "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)"

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

Payload della risposta:

{
  "data": [
    {
      "siteId": "my-org-myportal",
      "name": "Get Started",
      "id": "e0518597-ece2-4d7d-ba7c-d1793df0f8db"
    },
    {
      "siteId": "my-org-myportal",
      "name": "Test",
      "id": "61c1014c-89c9-40e6-be3c-69cca3505620"
    }
  ],
  "status": "success",
  "message": "all ApiCategory items returned",
  "requestId": "602661435"
}

Dove:

  • id: L'ID dell'elemento della categoria. Ad esempio, 61c1014c-89c9-40e6-be3c-69cca3505620.

Aggiungere una categoria

Per aggiungere una categoria:

Console

  1. Accedi alla pagina Categorie.

  2. Aggiungi una categoria.

    UI di Cloud Console

    1. Fai clic su + Categoria.
    2. Inserisci il nome della nuova categoria.
    3. (Facoltativo) Seleziona una o più API da taggare nella categoria.
    4. Fai clic su Aggiungi.

    UI classica

    1. Fai clic su Aggiungi.
    2. Inserisci il nome della nuova categoria.
    3. (Facoltativo) Seleziona una o più API da taggare nella categoria.
    4. Fai clic su Crea.

curl

Per aggiungere una categoria utilizzando organizations.sites.apicategories.create:

curl  -X POST "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • CATEGORY_NAME con il nome della categoria. Ad esempio, demo-backend.

Payload della risposta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "API category created",
  "requestId": "295617049"
}

Modificare una categoria

Per modificare una categoria:

Console

  1. Accedi alla pagina Categorie.

  2. Modifica una categoria.

    UI di Cloud Console

    1. Nella riga della categoria che vuoi modificare, fai clic su Altro > Modifica.
    2. Modifica il nome della categoria.
    3. Aggiungi o rimuovi i tag API.
    4. Fai clic su Aggiungi.

    UI classica

    1. Accedi alla pagina Categorie.
    2. Posiziona il cursore sulla categoria che vuoi modificare per visualizzare il menu delle azioni.
    3. Fai clic su Modifica.
    4. Modifica il nome della categoria.
    5. Aggiungi o rimuovi i tag API.
    6. Fai clic su Salva.

curl

Per modificare una categoria utilizzando organizations.sites.apicategories.patch:

curl -X PATCH "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID"  \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json" \
    -d '{"name": "CATEGORY_NAME" }'

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • CATEGORY_ID: l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Recupera l'ID categoria con il comando list API categories.
  • CATEGORY_NAME con il nome della categoria. Ad esempio, demo-backend.

Payload della risposta:

{
  "data": {
    "siteId": "my-org-myportal",
    "name": "demo-backend-test",
    "id": "ed0b6c1d-eb49-419f-8475-9a428ed5b8d1"
  },
  "status": "success",
  "message": "ApiCategory updated",
  "requestId": "192211979"
}

Eliminare una categoria

Quando elimini una categoria, vengono eliminati anche tutti i tag API associati.

Per eliminare una categoria:

Console

  1. Accedi alla pagina Categorie.

  2. Eliminare una categoria.

    UI di Cloud Console

    Nella riga della categoria che vuoi modificare, fai clic su Altro > Elimina.

    UI classica

    1. Posiziona il cursore sopra la categoria che vuoi eliminare per visualizzare il menu delle azioni.
    2. Fai clic su Elimina.

  3. Fai clic su Elimina per confermare.

curl

Per eliminare una categoria utilizzando organizations.sites.apicategories.delete:

curl -X DELETE "https://apigee.googleapis.com/v1/organizations/ORG_NAME/sites/SITE_ID/apicategories/CATEGORY_ID" \
    -H "Authorization: Bearer $(gcloud auth print-access-token)" \
    -H "Content-Type: application/json"

Sostituisci quanto segue:

  • ORG_NAME con il nome dell'organizzazione. Ad esempio, my-org.
  • SITE_ID con il nome del portale, nel formato ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome dell'organizzazione e PORTAL_NAME è il nome del portale convertito in tutte le lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • CATEGORY_ID: l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Recupera l'ID categoria con il comando list API categories.

Payload della risposta:

{
  "status": "success",
  "message": "ApiCategory deleted",
  "requestId": "1610396471"
}

Risolvere i problemi relativi alle API pubblicate

Le sezioni seguenti forniscono informazioni per aiutarti a risolvere errori specifici con le nostre API pubblicate.

Errore: impossibile recuperare l'errore restituito durante l'utilizzo di Prova questa API

Quando utilizzi Prova questa API, se viene restituito l'errore TypeError: Failed to fetch, considera le seguenti possibili cause e soluzioni:

  • Per gli errori relativi ai contenuti misti, l'errore potrebbe essere causato da un problema noto di swagger-ui. Una possibile soluzione alternativa è assicurarsi di specificare HTTPS prima di HTTP nella definizione di schemes nel documento OpenAPI. Ad esempio:

    schemes:
   - https
   - http

  • Per gli errori di limitazione della condivisione delle risorse tra origini (CORS), assicurati che CORS sia supportato per i tuoi proxy API. CORS è un meccanismo standard che consente le richieste tra origini lato client. Consulta Configurazione del proxy API per supportare il riquadro Prova questa API.

Errore: campo dell'intestazione della richiesta non consentito

Quando utilizzi Prova questa API, se ricevi un errore Request header field not allowed, simile al seguente esempio, potrebbe essere necessario aggiornare le intestazioni supportate nei criteri CORS. Ad esempio:

field content-type is not allowed by Access-Control-Allow-Headers in preflight
response

In questo esempio, devi aggiungere l'intestazione content-type alla sezione Access-Control-Allow-Headers nella policy AssignMessage CORS, come descritto in Collegamento di una policy Aggiungi CORS a un nuovo proxy API.

Errore: accesso negato durante la chiamata di un proxy API utilizzando OAuth 2.0

La policy OAuthV2 della console Google Cloud restituisce una risposta del token che contiene determinate proprietà non conformi alla RFC. Ad esempio, il criterio restituirà un token con il valore BearerToken, anziché il valore Bearer conforme a RFC previsto. Questa risposta token_type non valida può generare un errore Access denied quando utilizzi Prova questa API.

Per correggere questo problema, puoi creare una policy JavaScript o AssignMessage per trasformare l'output della policy in un formato conforme. Per ulteriori informazioni, vedi comportamento non conforme alla RFC.