Gestisci specifiche API

Questa pagina si applica a Apigee e Apigee ibrido.

Questo documento descrive come gestire le specifiche API nell'hub API. Consulta anche Introduzione alle specifiche API.

Aggiungi una specifica API a una versione

Puoi aggiungere una o più specifiche API a una versione API. Scegli una di queste opzioni:

Aggiungi una specifica quando crei una versione

Utilizzando solo la UI, puoi aggiungere una specifica API nel momento in cui crei una versione. Puoi fornire l'URL a una specifica a cui puoi accedere o caricare un file delle specifiche direttamente dal tuo sistema.

Console

Per aggiungere una specifica a una nuova versione:

  1. Per iniziare, segui i passaggi elencati in Creare una versione API. Quando raggiungi la pagina Aggiungi una nuova versione, puoi aggiungere un file di specifica alla versione:
    1. Inserisci un nome visualizzato per il file delle specifiche. Puoi utilizzare il nome che desideri.
    2. Seleziona il tipo di file delle specifiche. Il tipo di specifica è un attributo di sistema configurabile. Vedi anche Attributi di sistema.
    3. Fornisci un URI che rimandi a un file di specifiche API valido a cui hai accesso oppure passa a un file di specifiche API sul tuo sistema.
  2. Completa la compilazione della pagina Aggiungi una nuova versione, quindi fai clic su Crea quando hai finito.

Aggiungi una specifica a una versione esistente

Puoi utilizzare la UI o l'API REST per aggiungere una specifica dell'API a una versione esistente.

Console

Per aggiungere una specifica direttamente a una versione:

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione da modificare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Seleziona un'API.
  5. Fai clic su Aggiungi file delle specifiche.
  6. Inserisci un nome visualizzato per il file delle specifiche. Puoi utilizzare il nome che desideri.
  7. Seleziona il tipo di file delle specifiche. Il tipo di specifica è un attributo di sistema configurabile. Vedi anche Attributi di sistema.
  8. Fornisci un URI che rimandi a un file di specifiche API valido a cui hai accesso oppure passa a un file di specifiche API sul tuo sistema.
  9. Seleziona la versione a cui aggiungere il file delle specifiche.
  10. Fai clic su Crea.

REST

Per aggiungere una specifica API a una versione, utilizza l'API Add API spec:

curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  'https://apihub.googleapis.com/v1/projects/API_PROJECT/locations/API_LOCATION/apis/API_ID/versions/VERSION_ID/specs?spec_id=SPEC_ID' \
  -d "DATA_FILE or URI"

Sostituisci quanto segue:

  • API_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • API_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco di una risorsa API.
  • VERSION_ID: l'ID di una versione collegata alla risorsa API.
  • SPEC_ID: (facoltativo) l'identificatore della specifica. Se non viene fornito, verrà utilizzato un ID generato dal sistema. Il nome deve essere una stringa di 4-63 caratteri, dove i caratteri validi sono /[a-z][0-9]-/.
  • DATA_FILE or URI: un file con codifica Base64 contenente una specifica API valida o un link a una specifica. Vedi l'esempio REST.

Esempio REST

In questo esempio, crea una nuova specifica nell'hub API con una specifica OpenAPI codificata in Base64. Al momento del caricamento, l'hub API analizza la specifica e crea una nuova entità della specifica che include metadati descrittivi e set di entità operazioni e definizione. 

curl -X POST \
  -H "Authorization: Bearer $(gcloud auth print-access-token)" \
  -H "Content-Type: application/json" \
  -d "@data.json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs?spec_id=dstreetcarts-spec

Esempio di output:

{
    "name": "projects/common-dev-1/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
    "displayName": "Test Spec 1",
    "specType": {},
    "contents": {
      "contents": [Base64-encoded contents of an OpenAPI 3.0.2 file] },
    "details": {
      "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
      "openApiSpecDetails": {
        "format": "OPEN_API_SPEC_3_0",
        "version": "1.0.11"
      }
    },
    "createTime": "2024-04-04T22:39:05.674986Z",
    "updateTime": "2024-04-04T22:39:05.674986Z"
  }

Per restituire i dettagli delle specifiche:

curl -X GET -H "Authorization: Bearer $(gcloud auth print-access-token)" -H "Content-Type: application/json" \
  https://apihub.googleapis.com/v1/projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1

Output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1",
  "displayName": "Test Version 3",
  "documentation": {},
  "specs": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec"
  ],
  "apiOperations": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/listpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/createpets",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/deletepet",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/getpetbyid",
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/operations/updatepet"
  ],
  "definitions": [
    "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/definitions/pet"
  ],
  "createTime": "2024-04-04T14:53:57.299213423Z",
  "updateTime": "2024-04-04T14:53:58.027321138Z"
}

Specifiche elenco

Questa sezione spiega come elencare le specifiche associate a una versione dell'API.

Console

Per elencare le specifiche con l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione da controllare.
  6. Seleziona una versione.
  7. Tutte le specifiche collegate alla versione sono elencate nella sezione File delle specifiche.

REST

Per elencare le specifiche associate a una versione dell'API, utilizza l'API List specifiche:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs"
      -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.

Ottieni i dettagli della specifica

Questa sezione spiega come ottenere i dettagli di una specifica API associata a una versione.

Console

Per visualizzare i dettagli di una specifica utilizzando l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione contenente la specifica che vuoi controllare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione da controllare.
  6. Seleziona una versione.
  7. Nella sezione File delle specifiche, seleziona una specifica per visualizzarne i dettagli.

REST

Per visualizzare i dettagli di una specifica, utilizza l'API Ottieni i dettagli della specifica:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.

Esempio di output:

{
  "name": "projects/myproject/locations/us-central1/apis/streetcarts/versions/streetcartsv1/specs/dstreetcarts-spec",
  "displayName": "Test Spec 1",
  "details": {
    "description": "This is a sample Pet Store Server based on the OpenAPI 3.0 specification.\nYou can find out more about Swagger at [https://swagger.io](https://swagger.io).",
    "openApiSpecDetails": {
      "format": "OPEN_API_SPEC_3_0",
      "version": "1.0.11"
    }
  },
  "createTime": "2024-04-04T22:39:05.098508600Z",
  "updateTime": "2024-04-04T22:39:06.661264958Z"
}

Elimina una specifica API

Questa sezione spiega come eliminare una specifica API da una versione. L'eliminazione di una specifica comporta anche l'eliminazione delle operazioni associate dalla versione.

Console

Per eliminare le risorse API con l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione che contiene la specifica da eliminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica da eliminare.
  6. Seleziona la versione.
  7. Nella sezione File delle specifiche, seleziona Elimina dal menu Azioni nella riga della specifica che vuoi eliminare.
  8. Fai clic su Elimina.

REST

Per eliminare una risorsa API dall'hub API, utilizza l'API Delete API resource (Elimina risorsa API):

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X DELETE -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica da eliminare.

Modifica una specifica

Puoi modificare alcuni attributi di una specifica. Per un elenco di attributi che puoi aggiornare, consulta API Patch specifiche della versione.

REST

Per modificare una specifica con l'API REST:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID"
    -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X PATCH -H "Content-Type: application/json"
    '{
      "display-name": DISPLAY_NAME.  # Use the request body to specify attribute changes
      "contents": {
         "contents": Base64-encoded string
         "mimeType": MIME_TYPE
      }
    }'

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.
  • Corpo della richiesta: utilizza il corpo della richiesta per specificare gli attributi da modificare. Consulta Definizione di risorsa della specifica.

Visualizza i risultati lint delle specifiche

L'hub API fornisce un linter (strumento di convalida) integrato (spettrale) che convalida la specifica Open API dell'API. Consulta la sezione Convalidare le specifiche dell'API.

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione che contiene le specifiche che vuoi controllare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica da controllare.
  6. Fai clic su Risultati nella colonna Lint per visualizzare i risultati lint.

Ottieni contenuti della specifica

Questa funzionalità ti consente di esaminare i contenuti di una specifica che è stata caricata nell'hub API.

Console

Per visualizzare i dettagli di una specifica utilizzando l'interfaccia utente:

  1. Nella console Google Cloud, vai alla pagina dell'hub API.

    Vai all'hub API
  2. Fai clic su API.
  3. Individua l'API con la versione che contiene la specifica da eliminare. Utilizza Filtra per specificare le parole chiave per filtrare l'elenco delle API. Se necessario, utilizza la ricerca per individuare un'API.
  4. Fai clic su un'API per visualizzarne i dettagli.
  5. Nella scheda Versioni, individua la versione contenente la specifica da controllare.
  6. Fai clic sul nome della specifica per visualizzarne i contenuti.

REST

L'API recupera i contenuti non elaborati codificati Base64 di una specifica API che è stata caricata nell'hub API. Utilizza l'API Get specific content:

curl "https://apihub.googleapis.com/v1/projects/HUB_PROJECT/locations/HUB_LOCATION/apis/API_ID/versions/VERSION_ID/specs/SPEC_ID:contents"
  -H "Authorization: Bearer: $(gcloud auth print-access-token)" -X GET -H "Content-Type: application/json"

Sostituisci quanto segue:

  • HUB_PROJECT: il nome del progetto host dell'hub API. Il progetto host è stato selezionato durante il provisioning dell'hub API.
  • HUB_LOCATION: la località del progetto host. La località è stata scelta al momento del provisioning dell'hub API.
  • API_ID: l'ID univoco della risorsa API.
  • VERSION_ID: l'ID univoco della versione.
  • SPEC_ID: l'ID univoco della specifica.

Esempio di output:

{
  "contents": "Base64-encoded file contents"
}