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 tramite API

Il processo di pubblicazione delle API sul portale prevede due fasi:

  1. Seleziona il prodotto API che vuoi pubblicare sul tuo portale.
  2. Rendering della documentazione di riferimento dell'API dal documento OpenAPI o dallo schema GraphQL per consentire agli sviluppatori di app di acquisire informazioni sulle API. Per saperne di più, consulta la documentazione relativa all'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 dalla pubblicazione dell'API mediante un documento OpenAPI o uno schema GraphQL. Consulta:
  • Alla pagina delle API viene aggiunto un link alla pagina di riferimento delle API

    La pagina delle API (inclusa nel portale di esempio) fornisce un elenco di tutte le API pubblicate sul tuo portale, elencate in ordine alfabetico, con link alla rispettiva documentazione di riferimento per ulteriori informazioni. Se vuoi, puoi personalizzare quanto segue:

    • Immagine visualizzata per ogni scheda dell'API
    • Categorie utilizzate per il tagging delle API per consentire agli sviluppatori di scoprire le API correlate nella pagina delle API
    Pagina delle API nel portale in tempo reale che mostra due categorie e l'uso delle immagini Pagina delle API nel portale in tempo reale che mostra due categorie e l'uso delle immagini

SmartDocumenti (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 endpoint protetti utilizzando l'autenticazione di base, una chiave API o l'autenticazione 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 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 espanso Prova questa API

Riquadro espanso Prova questa API

Explorer GraphQL

Quando pubblichi un'API utilizzando uno schema GraphQL, GraphQL Explorer viene aggiunto al portale. GraphQL Explorer è un parco giochi interattivo per l'esecuzione di query sull'API. L'esplorazione si basa su GraphiQL, un'implementazione di riferimento dell'IDE GraphQL sviluppata dalla Foundation GraphQL.

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

GraphQL Explorer nel portale

GraphQL Explorer nel portale

Informazioni sulla documentazione dell'API

Ogni documento OpenAPI o GraphQL funge da fonte attendibile per tutto il ciclo di vita di un'API. Lo stesso documento viene utilizzato in ogni fase del ciclo di vita dell'API, dallo sviluppo alla pubblicazione fino al monitoraggio. Quando modifichi un documento, devi essere a conoscenza dell'impatto delle modifiche sull'API in altre fasi del ciclo di vita, come descritto in Cosa succede se modifico un documento?

Quando pubblichi l'API su un portale, salvi una versione del documento OpenAPI o GraphaphQL per visualizzare la documentazione di riferimento dell'API. Se modifichi il documento, puoi decidere di aggiornare la documentazione di riferimento dell'API pubblicata sul portale in modo da 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 autorizzazione del codice di autorizzazione OAuth 2.0 (spesso indicato come OAuth a tre vie), 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 tuo 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 la richiedono, come descritto nella sezione Registrazione delle app.

Configura il proxy API in modo da supportare il riquadro Prova questa API

Prima di pubblicare le API utilizzando un documento OpenAPI, devi configurare il proxy API per supportare l'esecuzione di richieste nel riquadro Prova questa API nella documentazione di riferimento dell'API SmartDocs, come indicato di seguito:

  • Aggiungi il supporto CORS ai tuoi 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 al criterio della stessa origine applicato 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 all'autenticazione.

Accesso di autorizzazione Requisiti di configurazione dei criteri
Nessuna o chiave API Per aggiungere il supporto CORS al proxy API, segui i passaggi descritti in Aggiungere il supporto CORS a un proxy API.
Autenticazione di base Svolgi i seguenti passaggi:
  1. Per aggiungere il supporto CORS al proxy API, segui i passaggi descritti in Aggiungere il supporto CORS a un proxy API.
  2. Nel criterio Aggiungi 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. Per aggiungere il supporto CORS al proxy API, segui i passaggi descritti in Aggiungere il supporto CORS a un proxy API.
  2. Nel criterio Aggiungi 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 a RFC nel tuo criterio OAuth 2.0. Per praticità, utilizza la soluzione OAuth 2.0 di esempio disponibile su GitHub o esegui questi passaggi:
    • Assicurati che l'elemento <GrantType> nel criterio OAuth 2.0 sia impostato su request.formparam.grant_type (parametro del modulo). Per maggiori informazioni, consulta <GrantType>.
    • Assicurati che il token_type nel criterio OAuth 2.0 sia impostato su Bearer e non il valore predefinito di BearerToken.

Gestione delle API

Gestisci le API come descritto nelle sezioni seguenti.

Esplora API

Usa la console o il comando curl per visualizzare le API disponibili nel portale.

Console

Per visualizzare il catalogo delle API:

  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 delle 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, specifiche associate e specifiche modificate

    Scheda API che mostra informazioni sulle API, tra cui nome, descrizione, visibilità, categorie, specifiche associate e specifiche modificate

    Come evidenziato nella figura precedente, la scheda API ti consente di:

arricciatura

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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

Vedi Note di impaginazione per istruzioni sull'uso della paginazione nel payload di risposta.

Payload 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: Tempo in cui l'articolo di catalogo è stato modificato per l'ultima volta, in millisecondi dall'epoca. Ad esempio, 1698165480000.
  • id: L'ID dell'articolo del catalogo. Ad esempio, 399668.

Note di impaginazione:

  • Dimensioni pagina: utilizza pageSize per specificare il numero di voci dell'elenco da restituire in una pagina. Il valore predefinito è 25 e il massimo è 100. Se ci sono altre pagine, nextPageToken viene completato 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 voci dell'elenco da restituire in una pagina. Ad esempio, 10.

    Payload 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 ne sono presenti 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 voci 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 portale:

Console

  1. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.

  3. Fai clic su Aggiungi.

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

  4. Seleziona il prodotto API che vuoi aggiungere al tuo portale.

  5. Tocca Avanti. Viene visualizzata la pagina Dettagli API.

  6. Configura il contenuto della documentazione di riferimento dell'API e la sua visibilità sul portale:

    Campo Descrizione
    Offerta pubblicata Seleziona Published (Pubblicata) per pubblicare l'API sul tuo portale. Deseleziona la casella di controllo se non vuoi pubblicare l'API. Puoi modificare l'impostazione in un secondo momento, come descritto in Pubblicare o annullare la pubblicazione di un'API.
    Titolo visualizzato 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 nella sezione Modificare il titolo visualizzato e la descrizione.
    Visualizza 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 nella sezione Modificare il titolo e la descrizione visualizzati.
    Imponi agli sviluppatori di specificare un URL di callback Abilita 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 relativa all'API

    Per utilizzare un documento OpenAPI:

    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 eseguire l'importazione.
    4. Fai clic su Seleziona.

    Per utilizzare uno schema GraphQL:

    1. Seleziona Diagramma grafico.
    2. Fai clic su Seleziona documento.
    3. Vai allo schema GraphQL e selezionalo.
    4. Fai clic su Seleziona.

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

    Visibilità

    Se non hai effettuato la registrazione alla release beta 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 effettuato la registrazione alla release beta della funzionalità di gestione dei segmenti di pubblico, seleziona una delle seguenti opzioni:

    • Pubblica (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.

    Immagine copertina Per visualizzare un'immagine sulla scheda dell'API nella pagina delle 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 per una scheda API. Quando specifichi l'URL di un'immagine esterna, l'immagine non verrà 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.
    Categorie

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

    • Seleziona una categoria dall'elenco a discesa.
    • Aggiungi una nuova categoria digitando il nome e premendo Invio. La nuova categoria viene aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.

  7. Fai clic su Salva.

arricciatura

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 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 visualizzata. Ad esempio, Simple hello world example.
  • ANON_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true abilita l'accesso anonimo degli utenti. Questa impostazione viene ignorata se hai effettuato la registrazione alla release beta della funzionalità di gestione dei segmenti di pubblico.
  • IMAGE_URL con l'URL di un'immagine esterna utilizzata 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, l'immagine non verrà caricata negli asset. Inoltre,il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme sulla 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 con l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa gli ID categoria con una virgola. Recupera l'ID categoria con il comando list API labels.

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

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

Payload 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: Tempo in cui l'articolo di catalogo è stato modificato per l'ultima volta, in millisecondi dall'epoca. Ad esempio, 1698165480000.
  • id: L'ID dell'articolo del catalogo. Ad esempio, 399668.

Modifica 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 portale.

Fai riferimento alle sezioni successive per informazioni sulle impostazioni di modifica specifiche.

Console

  1. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. In Dettagli API, apporta le modifiche necessarie. Consulta le descrizioni delle opzioni in Aggiungere un'API.
  6. Fai clic su Salva.

arricciatura

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 chiamata API.

  1. Ottieni un elenco delle API nel tuo portale utilizzando organizations.sites.apidocs/list per individuare l'id generata che identifica in modo univoco ciascuna 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

    Payload 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: Tempo in cui l'articolo di catalogo è stato modificato per l'ultima volta, in millisecondi dall'epoca. 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
    • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.

    Payload 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 mantenere nella chiamata organizations.sites.apidocs.update e modifica quelli 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 visualizzata. Ad esempio, Simple hello world example.
    • ANON_TRUE_OR_FALSE con true o false (impostazione predefinita), dove true abilita l'accesso anonimo degli utenti. Questa impostazione viene ignorata se hai effettuato la registrazione alla release beta della funzionalità di gestione dei segmenti di pubblico.
    • IMAGE_URL con l'URL di un'immagine esterna utilizzata 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, l'immagine non verrà caricata negli asset. Inoltre,il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dalle norme sulla 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 con l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa gli ID categoria con una virgola. Recupera l'ID categoria con il comando list API labels.
    • API_PRODUCT con il nome del prodotto API. Ad esempio, Hello World 2.

    Payload 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 di rendere le API disponibili agli sviluppatori di app per il consumo.

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

Console

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

arricciatura

Includi uno dei seguenti elementi nella chiamata a 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 a organizations.sites.apidocs.get per restituire i valori correnti:

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Gestisci 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. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

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

    • Pubblica (visibile a tutti) per consentire a tutti gli utenti di visualizzare la pagina.
    • Utenti autenticati per consentire solo agli utenti registrati di visualizzare la pagina.
    • Segmenti di pubblico selezionati per scegliere 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 solo agli utenti registrati di visualizzare la pagina.

  6. Fai clic su Invia.

arricciatura

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

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

Includi uno dei seguenti elementi nella chiamata a update:

  # When not enrolled in the beta 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 a organizations.sites.apidocs.get per restituire i valori correnti:

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Gestire l'URL di callback per un'API

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

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

Console

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

arricciatura

Includi uno dei seguenti elementi nella chiamata a 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 a organizations.sites.apidocs.get per restituire i valori correnti:

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Gestisci l'immagine per una scheda API

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

Per gestire l'immagine per una scheda API:

Console

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

  5. In Dettagli API:

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

    Quando specifichi un'immagine, specifica un'immagine con un URL esterno utilizzato per l'articolo del catalogo oppure un percorso file per i file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, l'immagine non verrà caricata negli asset. Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata dai criteri di sicurezza dei contenuti.

  6. Fai clic su Salva.

arricciatura

Includi quanto segue nella chiamata a 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 a organizations.sites.apidocs.get per restituire i valori correnti:

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Applica il tagging a un'API utilizzando le categorie

L'utilizzo delle categorie consente agli sviluppatori di app di scoprire le API correlate. Vedi anche Gestire le categorie.

Per contrassegnare un'API con le categorie:

Console

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

  5. Fai clic sul campo Categorie ed esegui uno dei seguenti passaggi:

    • Seleziona una categoria dall'elenco a discesa.
    • Aggiungi una nuova categoria digitando il nome e premendo Invio. La nuova categoria verrà aggiunta alla pagina Categorie e resa disponibile durante l'aggiunta o la modifica di altre API.

  6. Ripeti la procedura per taggare l'API con più categorie.

  7. Fai clic su Salva.

arricciatura

Includi quanto segue nella chiamata a update:

  # Omit line for no categories

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

Utilizza il comando list_category per ottenere gli ID delle categorie.

Per modificare l'API:

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

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Modifica il titolo visualizzato e la descrizione

Per modificare il titolo e la descrizione visualizzati:

Console

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

arricciatura

Includi quanto segue nella chiamata a update:

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

Per modificare l'API:

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

    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 a organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modifica quelli da cambiare. Se ometti un'impostazione mutabile, 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 restituiti.

Rimuovere un'API

Per rimuovere un'API dal portale:

Console

  1. Accedi al catalogo delle API.
  2. Seleziona la scheda API, se non è già selezionata.
  3. Posiziona il cursore sull'API nell'elenco per visualizzare il menu Azioni.
  4. Fai clic su Elimina.

arricciatura

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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.

Payload risposta:

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

Gestisci la documentazione dell'API

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

Aggiorna la documentazione dell'API

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

Per caricare una versione diversa della documentazione dell'API:

Console

  1. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Nel riquadro Documentazione API, seleziona una delle seguenti opzioni:
    • Documento OpenAPI
    • Schema grafico
  6. Fai clic su Seleziona documento e scegli la versione più recente del documento.
  7. Per GraphQL, specifica l'URL endpoint.
  8. Fai clic su Salva.

arricciatura

Per aggiornare i contenuti della documentazione di 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.
  • DISPLAY_NAME con il nome visualizzato della documentazione dell'API. Ad esempio, Hello World 2.
  • CONTENTS con la stringa dei contenuti con codifica Base64 della documentazione dell'API. La maggior parte degli ambienti di sviluppo contiene un'utilità di conversione base64 oppure sono disponibili molti strumenti di conversione online.

Payload 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.
  • 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 dei contenuti con codifica Base64 della documentazione dell'API. La maggior parte degli ambienti di sviluppo contiene un'utilità di conversione base64 oppure sono disponibili molti strumenti di conversione online.

Payload 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 delle API viene visualizzata dal documento e aggiunta alla pagina API del portale in tempo reale.

Scarica 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

  • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.

    Payload risposta:

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

Dove:

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

Rimuovi la documentazione dell'API

Per rimuovere la documentazione dell'API:

Console

  1. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic sulla riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Nel riquadro Documentazione API, seleziona Nessuna documentazione.
  6. Fai clic su Salva.

arricciatura

Per rimuovere i contenuti dei documenti dell'API utilizzando un'API, cancelli 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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • API_DOC con il valore id generato del documento. Ad esempio, 399668. Per trovare questo valore, utilizza il comando list API docs.

Payload risposta:

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

Gestisci categorie

Codifica un'API utilizzando le categorie per consentire agli sviluppatori di app di trovare le API correlate nella pagina API del portale in tempo reale. Aggiungi e gestisci le categorie, come descritto nelle sezioni seguenti.

Esplora le categorie

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

Console

Per visualizzare la pagina Categorie:

  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.

  3. Fai clic sulla scheda Categorie. La scheda Categorie nel catalogo delle API mostra l'elenco delle categorie definite per il portale.

    Scheda Categorie in cui vengono visualizzati il nome della categoria, i nomi e il numero totale di API assegnate.

    Scheda Categorie in cui vengono visualizzati il nome della categoria, i nomi e il numero totale di API assegnate.

    Come evidenziato nella figura precedente, la pagina delle API ti consente di:

arricciatura

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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.

Payload 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.

Aggiungi una categoria

Per aggiungere una categoria:

Console

  1. Accedi alla pagina Categorie.
  2. Fai clic su Aggiungi.
  3. Inserisci il nome della nuova categoria.
  4. (Facoltativo) Seleziona una o più API da taggare per la categoria.
  5. Fai clic su Crea.

arricciatura

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 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 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. Posiziona il cursore sulla categoria da modificare per visualizzare il menu Azioni.
  3. Fai clic su Modifica.
  4. Modifica il nome della categoria.
  5. Aggiungi o rimuovi i tag API.
  6. Fai clic su Salva.

arricciatura

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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • CATEGORY_ID con l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Recupera l'ID categoria con il comando list API labels.
  • CATEGORY_NAME con il nome della categoria. Ad esempio, demo-backend.

Payload 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 relativi a quella categoria.

Per eliminare una categoria:

Console

  1. Accedi alla pagina Categorie.
  2. Posiziona il cursore sulla categoria da modificare per visualizzare il menu Azioni.
  3. Fai clic su Elimina.
  4. Fai clic su Elimina per confermare.

arricciatura

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 lettere minuscole e con spazi e trattini rimossi. Ad esempio, my-org-myportal.
  • CATEGORY_ID con l'ID della categoria. Ad esempio, bf6505eb-2a0f-47af-a00a-ded40ac72960. Recupera l'ID categoria con il comando list API labels.

Payload risposta:

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

Risolvere i problemi relativi alle API pubblicate

Le seguenti sezioni forniscono informazioni per aiutarti a risolvere errori specifici relativi alle nostre API pubblicate.

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

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

  • Per gli errori di contenuti misti, l'errore potrebbe essere causato da un problema noto dell'interfaccia utente comprensibile. Una possibile soluzione alternativa consiste nell'assicurarti di specificare HTTPS prima di HTTP nella definizione di schemes nel documento OpenAPI. Ad esempio:

    schemes:
   - https
   - http

  • In caso di errori relativi alle limitazioni di condivisione delle risorse tra origini (CORS), assicurati che CORS sia supportato per i proxy API. CORS è un meccanismo standard che consente le richieste multiorigine lato client. Consulta Configurazione del proxy API per il supporto del riquadro Prova questa API.

Errore: campo intestazione della richiesta non consentito

Quando utilizzi Prova questa API, se ricevi un errore Request header field not allowed simile all'esempio seguente, potresti dover aggiornare le intestazioni supportate nel criterio 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 nel criterio di AttributionMessage di CORS, come descritto in Collegare un criterio CORS a un nuovo proxy API.

Errore: accesso negato durante la chiamata a un proxy API con OAuth 2.0

Il criterio 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, invece del valore previsto compatibile con RFC Bearer. Questa risposta token_type non valida può causare un errore Access denied quando utilizzi Prova questa API.

Per risolvere il problema, puoi creare un criterio JavaScript o AttributionMessage per trasformare l'output del criterio in un formato conforme. Per maggiori informazioni, vedi comportamento non conforme a RFC.