Pubblicazione delle API

Questa pagina si applica a Apigee e Apigee ibridi.

Visualizza documentazione di Apigee Edge.

Pubblica le API nel tuo portale per renderle disponibili per il consumo per app come descritto nelle sezioni seguenti.

Panoramica della pubblicazione dell'API

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

  1. Seleziona il prodotto API che vuoi pubblicare sul tuo portale.
  2. Esegui il rendering della documentazione di riferimento dell'API dal tuo documento OpenAPI o GraphQL per consentire agli sviluppatori di app di conoscere le tue API. (Per ulteriori informazioni, vedi Informazioni sulla documentazione dell'API)

Che cosa viene pubblicato sul portale?

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

  • documentazione di riferimento API. L'interfaccia fornita dipende se pubblichi la tua API utilizzando un documento OpenAPI o uno schema GraphQL. Consulta:
  • Viene aggiunto un link alla pagina di riferimento delle API

    La pagina delle API (inclusa portale di esempio) fornisce un elenco di tutte le API pubblicate nel tuo portale, elencati in ordine alfabetico, con i link al rispettivo riferimento dell'API documentazione per ulteriori informazioni. Se vuoi, puoi personalizzare seguenti:

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

SmartDocumenti (OpenAPI)

Quando pubblichi un'API utilizzando un documento OpenAPI, il riferimento dell'API SmartDocs viene aggiunta al portale.

Gli sviluppatori possono esaminare la documentazione di riferimento dell'API SmartDocs e utilizzare il Prova questa API per effettuare una richiesta API e visualizzare l'output. Prova questa API funziona con endpoint non protetti o con endpoint protetti utilizzando 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 le specifiche pertinenti 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 le specifiche pertinenti ed eseguire l'API.

Fai clic su Schermo intero per espandere il riquadro Prova questa API. Il riquadro espanso ti consente di visualizzare Esempi di chiamate e codice di curl in vari formati, come HTTP, Python Node.js e altri, come mostrato di seguito.

Riquadro Prova questa API espanso

Riquadro Prova questa API espanso

Explorer GraphQL

Quando pubblichi un'API utilizzando uno schema GraphQL, viene usato GraphQL Explorer aggiunto al tuo portale. GraphQL Explorer è un parco giochi interattivo eseguire query sull'API. Lo strumento di esplorazione si basa su GraphiQL un'implementazione di riferimento dell'IDE GraphQL sviluppato da GraphQL di base.

Gli sviluppatori possono usare GraphQL Explorer per esplorare le documentazione interattiva, creare ed eseguire query, visualizzare i risultati delle query e scarica lo schema. Per proteggere l'accesso all'API, gli sviluppatori possono nel riquadro Intestazioni della richiesta. Per ulteriori informazioni su GraphQL, vedi graphql.org.

GraphQL Explorer nel portale

GraphQL Explorer nel portale

Informazioni sulla documentazione dell'API

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

Quando pubblichi la tua API su un portale, salvi una versione dell'API OpenAPI o Documento GraphQL per il rendering della documentazione di riferimento dell'API. Se modifichi documento, puoi decidere di aggiornare la documentazione di riferimento dell'API pubblicata su sul portale per riflettere le ultime modifiche.

Informazioni sugli URL di callback

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

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

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

Configura il proxy API in modo che supporti il riquadro Prova questa API

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

  • Aggiungi il supporto CORS ai proxy API per applicare il supporto multiorigine lato client richieste.
    CORS è un meccanismo standard che consente le chiamate JavaScript XMLHttpRequest (XHR) eseguite in una pagina web per interagire con risorse di domini non di origine. CORS è una soluzione comunemente implementata per 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 pannello Prova questa API nella documentazione di riferimento dell'API SmartDocs in base all'accesso per l'autenticazione.

Autorizzazione accesso Requisiti di configurazione dei criteri
Nessuna o chiave API Aggiungi il supporto CORS al proxy API, segui i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
Autenticazione di base Procedi nel seguente modo:
  1. Aggiungi il supporto CORS al proxy API, segui i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
  2. In Aggiungi criterio CORS, assicurati che L'intestazione Access-Control-Allow-Headers include i campi 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, segui i passaggi descritti in Aggiunta del supporto CORS a un proxy API.
  2. In Aggiungi criterio CORS, assicurati che L'intestazione Access-Control-Allow-Headers include i campi Attributo authorization. Ad esempio:
    <Header name="Access-Control-Allow-Headers">
  origin, x-requested-with, accept, content-type, authorization
</Header>
    .
  3. Risposta corretta comportamento non conforme a RFC nel criterio OAuth 2.0. Per praticità, utilizza la soluzione OAuth 2.0 di esempio fornita su GitHub oppure esegui queste operazioni: passaggi:
      .
    • Assicurati che l'elemento <GrantType> nel file OAuth 2.0 il criterio è impostato su request.formparam.grant_type (parametro modulo). Per ulteriori informazioni, vedi <GrantType>.
    • Assicurati che token_type nel criterio OAuth 2.0 sia impostato su Bearer e non sul valore predefinito BearerToken.

Gestione delle API

Gestisci le API come descritto nelle sezioni seguenti.

Esplora API

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

Console

Per visualizzare il catalogo delle API:

  1. Seleziona Pubblica > Portals 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 hanno è stato aggiunto al tuo portale.

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

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

    Come evidenziato nella figura precedente, 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.

Consulta le note sull'impaginazione per istruzioni sull'utilizzo l'impaginazione 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: Data e ora in cui l'elemento del 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 sull'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 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 voci 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 ne sono 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. Fai clic su Avanti. Viene visualizzata la pagina Dettagli API.

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

    Campo Descrizione
    Pubblicato 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 che viene visualizzato nel catalogo. Di predefinito, viene utilizzato il nome del prodotto API. Puoi cambiare la modalità di visualizzazione titolo in seguito, come descritto Modifica il titolo e la descrizione visualizzati.
    Visualizza descrizione Aggiorna la descrizione dell'API che viene visualizzata nella catalogo. Per impostazione predefinita, viene utilizzata la descrizione del prodotto API. Puoi modificare la descrizione visualizzata in un secondo momento, come descritto Modifica 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 Gestisci l'URL di callback per un'API.
    Documentazione dell'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 Upload File (Carica file) e carica un file.
      • Fai clic sulla scheda Importa da un URL e importa una specifica. specificando un nome e un URL da cui eseguire l'importazione.
    4. Fai clic su Seleziona.

    Per utilizzare uno schema GraphQL:

    1. Seleziona Schema GraphQL.
    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 Gestisci la documentazione dell'API.

    Visibilità

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

    • Pubblica (visibile a chiunque) 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 scegliere quelli specifici che vuoi poter vedere l'API.

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

    Immagine di visualizzazione Per visualizzare un'immagine nella scheda API della pagina API, fai clic su Seleziona immagine. Nella finestra di dialogo Seleziona immagine, seleziona un un'immagine esistente, carica una nuova immagine o fornisci l'URL di 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, l'immagine non sarà caricata asset; Inoltre, il caricamento dell'immagine nel portale integrato sarà soggetta alla sua disponibilità, che potrebbe essere bloccata o limitata da norme sulla sicurezza dei contenuti.
    Categorie

    Aggiungi le categorie con cui l'API verrà taggata per abilitare agli sviluppatori di app di scoprire le API correlate nella pagina delle API. A identifica una categoria:

    • Seleziona una categoria dall'elenco a discesa.
    • Aggiungi una nuova categoria digitandone il nome e premendo Invio. La nuova categoria viene aggiunta alla pagina Categorie e impostata disponibili quando aggiungi o modifichi altre API.

  7. Fai clic su Salva.

curl

Per aggiungere un'API al tuo 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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 (valore predefinito), dove true consente l'accesso anonimo agli utenti. Questa impostazione viene ignorata se hai effettuato la registrazione a La release beta della funzionalità di gestione dei segmenti di pubblico.
  • IMAGE_URL con l'URL di un'immagine esterna utilizzata per voce di catalogo o un percorso file file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, questa non verrà caricata le tue risorse; Inoltre,il caricamento dell'immagine nel portale integrato soggetta alla sua disponibilità, che potrebbe essere bloccata o limitata da norme sulla sicurezza del contenuto.
  • CALLBACK_TRUE_OR_FALSE con true o false (valore predefinito), dove true richiede che un utente del portale inserisca un URL durante la gestione dell'app.

  • CATEGORY_ID con l'ID della categoria. Ad esempio: bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa più ID categoria con un virgola. Recupera l'ID categoria con il valore elencare le categorie API .

  • PUBLISHED_TRUE_OR_FALSE con true o false (valore predefinito), 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: Data e ora in cui l'elemento del 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 l'API esistente nel tuo portale.

Consulta le sezioni successive per conoscere le impostazioni di modifica specifiche.

Console

  1. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Apporta le modifiche nella sezione Dettagli API. Vedi le descrizioni dei in Aggiungere un'API.
  6. Fai clic su Salva.

curl

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

Questo esempio illustra i passaggi necessari per modificare gli elementi pubblicati stato dell'API nel portale da true a false. Puoi modificare più di un'impostazione in una chiamata API, se necessario.

  1. Ottieni un elenco delle API nel tuo portale utilizzando organizations.sites.apidocs/list per individuare l'oggetto id 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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: Data e ora in cui l'elemento del 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 correnti 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.
    • API_DOC con i id generati 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 mantenere nel organizations.sites.apidocs.update e modifica i valori desiderati. per cambiare. Se ometti una riga, viene utilizzata l'impostazione predefinita. Per questo Ad 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 (valore predefinito), dove true consente l'accesso anonimo agli utenti. Questa impostazione viene ignorata se hai effettuato la registrazione a La release beta della funzionalità di gestione dei segmenti di pubblico.
    • IMAGE_URL con l'URL di un'immagine esterna utilizzata per voce di catalogo o un percorso file file immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, questa non verrà caricata le tue risorse; Inoltre,il caricamento dell'immagine nel portale integrato soggetta alla sua disponibilità, che potrebbe essere bloccata o limitata da norme sulla sicurezza del contenuto.
    • CALLBACK_TRUE_OR_FALSE con true o false (valore predefinito), dove true richiede che un utente del portale inserisca un URL durante la gestione dell'app.
    • CATEGORY_ID con l'ID della categoria. Ad esempio: bf6505eb-2a0f-47af-a00a-ded40ac72960. Separa più ID categoria con un virgola. Recupera l'ID categoria con il valore elencare le categorie API .
    • 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 con cui le API diventano disponibili per il consumo agli sviluppatori di app.

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 nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. In Dettagli API, seleziona o deseleziona Pubblicata (elencata nel catalogo). rispettivamente per pubblicare o annullare la pubblicazione dell'API sul tuo portale.
  6. Fai clic su Salva.

curl

Includi uno dei seguenti elementi nella update chiama:

  "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 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e 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. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

  5. Seleziona l'impostazione di visibilità. Se disponi hai effettuato la registrazione alla versione beta della funzionalità 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 quelli specifici da usare in grado di visualizzare la pagina. Consulta Gestione dei segmenti di pubblico per il portale.

    Altrimenti, 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.

curl

Se disponi gli utenti registrati alla versione beta della funzionalità di gestione dei segmenti di pubblico, usa nella console per gestire i segmenti di pubblico.

Se non hai effettuato la registrazione alla funzionalità di gestione dei segmenti di pubblico, la visibilità è gestiti con anonAllowed.

Includi uno dei seguenti elementi nella update chiama:

  # 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 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e payload restituito.

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 nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. In Dettagli API, seleziona o cancella Richiedi agli sviluppatori di specificare un URL di callback per specificare rispettivamente se un URL di callback è obbligatorio o meno.
  6. Fai clic su Salva.

curl

Includi uno dei seguenti elementi nella update chiama:

  "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 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e payload restituito.

Gestisci l'immagine per una scheda API

Gestisci l'immagine che viene visualizzata con una scheda API nella pagina API aggiungendo o la modifica dell'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 nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.

  5. In Dettagli API:

    • Fai clic su Seleziona immagine per specificare un'immagine nel caso in cui non sia presente alcuna immagine. selezionato.
    • 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 immagine archiviati nel portale, ad esempio /files/book-tree.jpg. Quando specifichi l'URL di un'immagine esterna, l'immagine non essere caricati nelle tue risorse. Inoltre, il caricamento dell'immagine nella portale sarà soggetto alla sua disponibilità, che potrebbe essere bloccata o limitata da norme sulla sicurezza del contenuto.

  6. Fai clic su Salva.

curl

Includi quanto segue nel update chiama:

  # 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 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e payload restituito.

Taggare un'API utilizzando le categorie

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

Per taggare 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 nella 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 digitandone il nome e premendo Invio. Il nuovo verrà aggiunta alla pagina Categorie e resa disponibile quando aggiunta o modifica di altre API.

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

  7. Fai clic su Salva.

curl

Includi quanto segue nel update chiama:

  # Omit line for no categories

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

Utilizza la elencare categorie per ottenere gli ID di categoria.

Per modificare l'API:

  1. Utilizza la chiamata a 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e payload restituito.

Modifica il titolo e la descrizione visualizzati

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

curl

Includi quanto segue nel update chiama:

  "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 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 organizations.sites.apidocs.update per modificare l'API. Includi i valori modificabili che vuoi conservare e modificare i valori da cambiare. Se ometti un'impostazione modificabile, il parametro 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 di passaggi, variabili e payload restituito.

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 delle azioni.
  4. Fai clic su Elimina.

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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.
  • API_DOC con i id generati 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"
}

Gestisci la documentazione dell'API

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

Aggiorna 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. Accedi al catalogo delle API.
  2. Fai clic sulla scheda API, se non è già selezionata.
  3. Fai clic nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Nel riquadro Documentazione API, seleziona una delle seguenti opzioni:
      .
    • Documento OpenAPI
    • Schema GraphQL
  6. Fai clic su Seleziona documento e seleziona la versione più recente del documento.
  7. Per GraphQL, specifica l'URL endpoint.
  8. 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.
  • API_DOC con i id generati 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 dei contenuti dell'API codificata in base64 documentazione. La maggior parte degli ambienti di sviluppo contiene base64 o ci sono 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.
  • API_DOC con i id generati 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 dei contenuti dell'API codificata in base64 documentazione. La maggior parte degli ambienti di sviluppo contiene base64 o ci sono 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 Pagina API del portale online.

Scarica la documentazione dell'API

Dopo aver pubblicato l'API, potrai scaricare in qualsiasi momento il file 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.

  • API_DOC con i id generati 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.

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 nella riga dell'API che vuoi modificare.
  4. Fai clic su Modifica.
  5. Nel riquadro Documentazione API, seleziona Nessuna documentazione.
  6. Fai clic su Salva.

curl

Per rimuovere i contenuti dei documenti dell'API utilizzando un'API, devi cancellare 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte minuscole e con spazi e trattini rimossi. Ad esempio: my-org-myportal.
  • API_DOC con i id generati 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

Codifica di un'API utilizzando le categorie per consentire agli sviluppatori di app di scoprire contenuti correlati API nella pagina API del portale online. Aggiungi e gestisci le categorie, come descritto di seguito sezioni.

Esplora categorie

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

Console

Per visualizzare la pagina Categorie:

  1. Seleziona Pubblica > Portals 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 che hai definito per il tuo portale.

    Scheda Categorie che mostra il nome della categoria, i nomi e il numero totale di API assegnate.

    Scheda Categorie che mostra 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:

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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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.

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. Facoltativamente, seleziona una o più API per il tagging della categoria.
  5. 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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. Posiziona il cursore sulla categoria che vuoi modificare per visualizzarla. 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.

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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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 valore elencare le categorie API .
  • 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 relativi tag API.

Per eliminare una categoria:

Console

  1. Accedi alla pagina Categorie.
  2. Posiziona il cursore sulla categoria che vuoi modificare per visualizzare il menu delle azioni.
  3. Fai clic su Elimina.
  4. 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 modulo ORG_NAME-PORTAL_NAME, dove ORG_NAME è il nome del organizzazione e PORTAL_NAME è il nome del portale convertito tutte 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 valore elencare le categorie API .

Payload della risposta:

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

Risolvi i problemi relativi alle API pubblicate

Le seguenti sezioni forniscono informazioni per aiutarti a risolvere i problemi con le API pubblicate.

Errore: impossibile recuperare l'errore restituito quando si utilizza Prova questa API

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

  • In caso di errori di contenuti misti, l'errore può essere causato da un noto problema di swagger-ui. Una possibile soluzione è assicurarsi di specificare HTTPS prima di HTTP la definizione di schemes nel documento OpenAPI. Ad esempio:

    schemes:
   - https
   - http

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

Errore: campo intestazione della richiesta non consentito

Quando utilizzi Prova questa API, se ricevi un Request header field not allowed simile all'esempio seguente, potrebbe essere necessario 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 Access-Control-Allow-Headers del criterio CORSAssignMessage, come descritti in Collegamento di un criterio Aggiungi CORS a un nuovo proxy API.

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

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

Per risolvere il problema, puoi creare un criterio JavaScript oAssignMessage per trasformare l'output dei criteri in un formato conforme. Per ulteriori informazioni, vedi comportamenti non compatibili con RFC.