Esegui il provisioning dell'hub API dalla riga di comando

Questa pagina si applica ad Apigee e Apigee hybrid.

Questo documento spiega come eseguire il provisioning di API Hub dalla riga di comando. Se preferisci eseguire il provisioning dell'hub API utilizzando l'interfaccia utente in stile guidata, consulta Eseguire il provisioning dell'hub API nella console Cloud.

Prima di iniziare

1. Sign in to your Google Cloud account. If you're new to Google Cloud, create an account to evaluate how our products perform in real-world scenarios. New customers also get $300 in free credits to run, test, and deploy workloads.

2. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

3. Make sure that billing is enabled for your Google Cloud project.

4. In the Google Cloud console, on the project selector page, select or create a Google Cloud project.

   Note: If you don't plan to keep the resources that you create in this procedure, create a project instead of selecting an existing project. After you finish these steps, you can delete the project, removing all resources associated with the project.

   Go to project selector

5. Make sure that billing is enabled for your Google Cloud project.

6. Make sure that you have the following role or roles on the project:

   • roles/serviceusage.serviceUsageAdmin
   • roles/cloudkms.admin
   • roles/apihub.provisioningAdmin
   • roles/resourcemanager.projectIamAdmin

   Check for the roles

   1. In the Google Cloud console, go to the IAM page.

      Go to IAM
   2. Select the project.

   3. In the Principal column, find all rows that identify you or a group that you're included in. To learn which groups you're included in, contact your administrator.

   4. For all rows that specify or include you, check the Role column to see whether the list of roles includes the required roles.

   Grant the roles

   1. In the Google Cloud console, go to the IAM page.

      Vai a IAM
   2. Seleziona il progetto.
   3. Fai clic su Concedi accesso.

   4. Nel campo Nuovi principali, inserisci il tuo identificatore utente. In genere si tratta dell'indirizzo email di un Account Google.

   5. Nell'elenco Seleziona un ruolo, seleziona un ruolo.
   6. Per concedere altri ruoli, fai clic su Aggiungi un altro ruolo e aggiungi ogni ruolo aggiuntivo.
   7. Fai clic su Salva.

   Riepilogo della procedura

   I passaggi per il provisioning sono i seguenti:

   1. Passaggio 1: attiva le API. Per il funzionamento dell'hub API Apigee, devi abilitare un insieme di API Google Cloud.
   2. Passaggio 2: crea l'identità del servizio dell'hub API Apigee. L'identità servizio consente all'istanza dell'hub API di chiamare le API Google Cloud di cui ha bisogno per eseguire le sue operazioni.
   3. Passaggio 3: Configura la crittografia. Puoi scegliere se utilizzare un approccio Google-owned and Google-managed encryption key (GMEK) o una chiave di crittografia gestita dal cliente (CMEK) per criptare e decriptare i dati at-rest dell'API. Consulta Confronto tra CMEK e crittografia di proprietà di Google Google-owned and Google-managed encryption keys.
   4. Passaggio 4: crea l'istanza dell'hub API. Per completare l'operazione, devi registrare il progetto host e creare l'istanza dell'hub API.

   Passaggi di provisioning

   Assicurati di soddisfare i prerequisiti descritti in Prima di iniziare.

   Passaggio 1: abilita le API

   Per eseguire il provisioning dell'hub API, devi abilitare le seguenti API nel tuo Google Cloud progetto:

   Autorizzazioni richieste per questa attività

   Puoi assegnare al provisioning dell'hub API Apigee un ruolo predefinito che includa le autorizzazioni necessarie per completare questa attività oppure autorizzazioni più granulari per fornire il privilegio minimo necessario. Consulta Ruoli predefiniti e Autorizzazioni di abilitazione delle API.

   1. Abilita le API Google Cloud richieste eseguendo il seguente comando services enable:

      gcloud services enable apihub.googleapis.com \
          cloudkms.googleapis.com --project=YOUR_PROJECT_ID

      dove YOUR_PROJECT_ID è l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.

   Passaggio 2: crea l'identità del servizio dell'hub API Apigee

   L'identità di servizio consente all'istanza dell'hub API di chiamare le API Google Cloud di cui ha bisogno per eseguire le sue operazioni.

   1. Crea l'identità del servizio:

      gcloud beta services identity create --service=apihub.googleapis.com \
        --project=YOUR_PROJECT_ID

      dove YOUR_PROJECT_ID è l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.

   2. Verifica che l'agente sia stato creato correttamente. La risposta include il nome dell'agente nel seguente formato: [e-mail]. Ad esempio:

      Service identity created: [e-mail]

      Tieni presente che dovrai utilizzare questa identità servizio in un passaggio successivo.

   Passaggio 3: configura la crittografia

   In questo passaggio, configuri la modalità di gestione della crittografia dei dati nell'istanza dell'hub API. Puoi utilizzare una Google-owned and Google-managed encryption key (GMEK) o creare la tua chiave di crittografia gestita dal cliente (CMEK). Consulta Confronto tra CMEK e crittografia di proprietà di Google Google-owned and Google-managed encryption keys.

   Passaggi CMEK

   Se vuoi utilizzare CMEK per la crittografia dei dati, segui questi passaggi:

   1. Crea una chiave automatizzata e una chiave di crittografia del database di runtime. Se vuoi, puoi utilizzare una chiave e un mazzo di chiavi CMEK esistenti. Tieni presente che la chiave deve essere creata nella stessa posizione in cui prevedi di creare l'istanza dell'hub API.

      1. Crea un nuovo mazzo di chiavi:

         Il nome del portachiavi deve essere univoco per la tua organizzazione. Se crei una seconda regione o una successiva, il nome non può essere uguale a quello di un'altra chiave automatizzata.

         gcloud kms keyrings create KEY_RING_NAME \
           --location KEY_RING_LOCATION --project YOUR_PROJECT_ID

         Dove:

         • KEY_RING_NAME: il nome del keyring da creare.
         • KEY_RING_LOCATION: la posizione fisica del portachiavi. Questa posizione deve essere la stessa che prevedi di utilizzare per l'istanza dell'hub API che creerai in un passaggio successivo. Devi utilizzare una delle seguenti località supportate:

           Descrizione della regione	Nome regione
           Iowa	us-central1
           Virginia del Nord	us-east4
           Oregon	us-west1
           Belgio	europe-west1
           Londra	europe-west2
           Singapore	asia-southeast1
           Mumbai	asia-south1
           San Paolo	southamerica-east1
           Sydney	australia-southeast1

         • YOUR_PROJECT_ID: l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.

      2. Crea la chiave di crittografia e aggiungila al portachiavi:

         gcloud kms keys create KEY_NAME \
           --keyring KEY_RING_NAME \
           --location KEY_LOCATION \
           --purpose "encryption" \
           --project YOUR_PROJECT_ID

         Dove:

         • KEY_NAME: il nome della chiave del database che stai creando.
         • KEY_RING_NAME: il nome del keyring appena creato.
         • KEY_LOCATION: la posizione fisica della chiave. Utilizza la stessa posizione utilizzata per creare il keyring.

      3. Recupera l'ID chiave:

         gcloud kms keys list \
           --location=KEY_LOCATION \
           --keyring=KEY_RING_NAME \
           --project=YOUR_PROJECT_ID

         L'ID chiave ha la seguente sintassi (simile a un percorso file). Conserva questo ID chiave, poiché dovrai utilizzarlo in un passaggio successivo:

         projects/YOUR_PROJECT_ID/locations/KEY_LOCATION/keyRings/KEY_RING_NAME/cryptoKeys/KEY_NAME

      4. Concedi all'agente di servizio Apigee l'accesso per utilizzare la nuova chiave:

         gcloud kms keys add-iam-policy-binding KEY_NAME \
           --location KEY_LOCATION \
           --keyring KEY_RING_NAME \
           --member serviceAccount:SERVICE_ACCOUNT \
           --role roles/cloudkms.cryptoKeyEncrypterDecrypter \
           --project YOUR_PROJECT_ID

         Dove: SERVICE_ACCOUNT è l'ID dell'account di servizio creato nel passaggio 2. L'ID sarà simile al seguente: [e-mail].

         Questo comando associa la chiave all'agente di servizio dell'hub API Apigee.

         Al termine della richiesta, gcloud risponde con un messaggio simile al seguente:

         Updated IAM policy for key [runtime].
         bindings:
         - members:
           - serviceAccount:[e-mail]
           role: roles/cloudkms.cryptoKeyEncrypterDecrypter
         etag: BwWqgEuCuwk=
         version: 1

         Se ricevi un messaggio di errore simile al seguente:

         INVALID_ARGUMENT: Role roles/cloudkms.cryptokms.cryptoKeyEncrypterDecrypter is not supported for this resource.

         Assicurati di aver utilizzato il numero del progetto e non il nome del progetto nell'indirizzo email dell'account di servizio.

   Passaggi GMEK

   Se vuoi utilizzare la chiave GMEK per la crittografia dei dati, vai al passaggio successivo, Passaggio 4: crea l'istanza dell'hub API. Non è richiesta alcuna ulteriore configurazione delle chiavi.

   Passaggio 4: crea l'istanza dell'hub API

   Un progetto host è il Google Cloud progetto in cui eseguirai il provisioning dell'hub API Apigee. Puoi eseguire il provisioning di una sola istanza dell'hub API per progetto host.

   1. Registra il progetto host:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -d '{
        "gcpProject": "projects/YOUR_PROJECT_ID"
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/hostProjectRegistrations?host_project_registration_id=HOST_ID

      Dove:

      • YOUR_PROJECT_ID: l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.
      • PROJECT_LOCATION: la località fisica (regione) in cui vuoi ospitare l'istanza dell'hub API Apigee. Devi utilizzare la stessa posizione utilizzata per creare la chiave e la chiave automatizzata CMEK. Le regioni supportate sono:

        Descrizione della regione	Nome regione
        Iowa	us-central1
        Virginia del Nord	us-east4
        Oregon	us-west1
        Belgio	europe-west1
        Londra	europe-west2
        Singapore	asia-southeast1
        Mumbai	asia-south1
        San Paolo	southamerica-east1
        Sydney	australia-southeast1

      • HOST_ID: il nome del progetto host.
   2. Crea l'istanza dell'hub API:

      Con CMEK

      Se hai utilizzato CMEK per la crittografia dei dati, esegui il seguente comando:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "cmekKeyName":"KEY_NAME",
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"CMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      Dove:

      • KEY_NAME (obbligatorio): il nome completo della chiave CMEK. Questo nome è stato restituito al momento della creazione della chiave. Ad esempio: projects/YOUR_PROJECT_ID/locations/HOST_LOCATION/hostProjectRegistrations/HOST_ID.
      • VERTEX_LOCATION (Facoltativo): specifica la posizione multiregione in cui archiviare i dati di ricerca basati su Vertex AI, ovvero i dati associati alla funzionalità Ricerca semantica dell'hub API. Per questo valore puoi utilizzare us o eu. Se non vuoi utilizzare nessuna di queste regioni multiple, puoi disattivare la ricerca semantica omettendo questo parametro.
      • encryptionType (obbligatorio) Devi utilizzare CMEK.
      • YOUR_PROJECT_ID è l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.
      • PROJECT_LOCATION: devi utilizzare la stessa località utilizzata per registrare il progetto host.
      • INSTANCE_ID: il nome dell'istanza dell'hub API. Questo valore deve contenere da 4 a 40 caratteri e i caratteri validi sono /[a-z][A-Z][0-9]-_/.

      Con GMEK

      Se utilizzi la chiave GMEK per la crittografia dei dati, esegui il seguente comando:

      curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
        -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" -d '{
        "config":{
          "vertexLocation":"VERTEX_LOCATION",
          "encryptionType":"GMEK"
          }
        }' https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/apiHubInstances?api_hub_instance_id=INSTANCE_ID

      Dove:

      • VERTEX_LOCATION (Facoltativo): specifica la posizione multiregione in cui archiviare i dati di ricerca basati su Vertex AI, ovvero i dati associati alla funzionalità Ricerca semantica dell'hub API. Per questo valore puoi utilizzare us o eu. Se non vuoi utilizzare nessuna di queste regioni multiple, puoi disattivare la ricerca semantica omettendo questo parametro.
      • encryptionType deve essere GMEK. Se non fornisci un tipo di crittografia, il valore predefinito è GMEK.
      • YOUR_PROJECT_ID è l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.
      • PROJECT_LOCATION: devi utilizzare la stessa località utilizzata per registrare il progetto host.
      • INSTANCE_ID: il nome dell'istanza dell'hub API. Questo valore deve contenere da 4 a 40 caratteri e i caratteri validi sono /[a-z][A-Z][0-9]-_/.

   (Facoltativo) Passaggio 5: crea un allegato del progetto di runtime

   Se hai eseguito il provisioning dell'hub API in un progetto con proxy Apigee, esegui questo passaggio facoltativo per registrare automaticamente i proxy nell'hub API.

   curl -X POST -H "Authorization: Bearer $(gcloud auth print-access-token)" \
     -H "Content-Type: application/json" -H "X-Google-GFE-Can-Retry: yes" \
     https://apihub.googleapis.com/v1/projects/YOUR_PROJECT_ID/locations/PROJECT_LOCATION/runtimeProjectAttachments?runtimeProjectAttachmentId=YOUR_PROJECT_ID

   Dove:

   • YOUR_PROJECT_ID è l'ID progetto Cloud che hai creato nella sezione Prima di iniziare.
   • PROJECT_LOCATION: devi utilizzare la stessa località utilizzata per registrare il progetto host.

   Passaggi successivi

   Ora puoi iniziare a utilizzare l'hub API:

   • Esamina i ruoli e le autorizzazioni necessari per utilizzare API Hub
   • Configura gli attributi dell'hub API:
     • Gestire gli attributi
     • Guida rapida: crea e modifica gli attributi
   • Registra una risorsa API:
     • Gestire le risorse API
     • Guida rapida: registra un'API
   • Aggiungi una versione dell'API:
     • Panoramica delle versioni
     • Guida rapida: crea una versione dell'API