Sincronizzazione della documentazione personalizzata tramite un'API

API Open   |  gRPC

Il 21 marzo 2022 è stato ritirato il portale Cloud Endpoints. Il portale Cloud Endpoints non sarà più disponibile dopo il 21 marzo 2023. Il traffico API gestito da Cloud Endpoints non è interessato da questa modifica. Per maggiori informazioni, consulta la pagina Ritiro delle funzionalità.

Il portale fornisce un'API speciale per la sincronizzazione dei contenuti personalizzati. Per chiamare questa API devi:

1. Sincronizzare manualmente i contenuti personalizzati almeno una volta.
2. Crea un account di servizio con l'autorizzazione e la chiave appropriate.
3. Effettua la richiesta HTTP per sincronizzare i contenuti.

Questo documento fornisce istruzioni per creare un account di servizio e fornisce esempi di esecuzione della richiesta tramite Python o tramite la riga di comando.

Creazione di un account di servizio autorizzato

Per utilizzare un'API per sincronizzare i contenuti personalizzati, devi avere un account di servizio con l'autorizzazione e la chiave corrette. Per creare l'account di servizio, assegnagli il ruolo appropriato e ottieni il file della chiave necessario, segui queste istruzioni:

console

1. Crea un account di servizio:

   1. In Google Cloud Console, vai alla pagina Account di servizio.

      Vai a Account di servizio

   2. Seleziona il progetto che la tua API è stata configurata per l'uso.

   3. Fai clic su Crea account di servizio.

   4. Nel campo Nome account di servizio, inserisci un nome. Google Cloud Console compila il campo ID account di servizio in base a questo nome.

   5. (Facoltativo) Nel campo Descrizione account di servizio, inserisci una descrizione per l'account di servizio.

   6. Fai clic su Crea e continua.

   7. Fai clic su Fine per completare la creazione dell'account di servizio.

      Non chiudere la finestra del browser. Lo utilizzerai nel passaggio successivo.

2. Scarica una chiave JSON per l'account di servizio appena creato:

   1. In Google Cloud Console, fai clic sull'indirizzo email dell'account di servizio che hai creato.
   2. Fai clic su Chiavi.
   3. Fai clic su Aggiungi chiave, quindi su Crea nuova chiave.

   4. Fai clic su Crea. Il file di una chiave JSON viene scaricato sul computer.

      Assicurati di archiviare il file della chiave in modo sicuro, perché può essere utilizzato per l'autenticazione come account di servizio. Puoi spostare e rinominare il file come preferisci.

   5. Fai clic su Chiudi.

3. Nella console Google Cloud, vai alla pagina Endpoint e servizi nel tuo progetto.

   Servizi endpoint

4. Fai clic sul nome dell'API per cui devi sincronizzare i contenuti personalizzati per modificarne le autorizzazioni di accesso.

5. Se il riquadro laterale di autorizzazioni non è aperto, fai clic su +Autorizzazioni.

6. Per concedere all'account di servizio creato l'accesso all'API, inserisci l'indirizzo email dell'account di servizio creato nel campo Aggiungi membri.

7. Nell'elenco a discesa Seleziona un ruolo, fai clic su Gestione servizio e seleziona il ruolo Editor configurazione servizio per l'account di servizio.

Complimenti! Hai creato l'account di servizio, scaricato la relativa chiave privata in un file JSON e assegnato il ruolo corretto all'account di servizio.

gcloud

1. Inserisci il comando seguente per visualizzare gli ID progetto per i progetti Google Cloud:

   gcloud projects list
   

2. Sostituisci [YOUR_PROJECT_ID] nel comando seguente per impostare il progetto predefinito su quello in cui si trova la tua API:

   gcloud config set project [YOUR_PROJECT_ID]
   

   Importante: devi creare l'account di servizio nello stesso progetto in cui si trova l'API.

3. Assicurati che Google Cloud CLI (gcloud) sia autorizzato ad accedere ai tuoi dati e servizi su Google Cloud:

   gcloud auth login
   

   Se disponi di più account, assicurati di scegliere quello che fa parte del progetto Google Cloud in cui si trova l'API. Se esegui gcloud auth list, l'account selezionato viene visualizzato come account attivo per il progetto.

4. Per creare un account di servizio, esegui il comando seguente e sostituisci [SERVICE_ACCOUNT_NAME] e [Service Account to Sync Custom Content] con il nome e il nome visualizzati che vuoi utilizzare:

   gcloud iam service-accounts create [SERVICE_ACCOUNT_NAME] \
     --display-name "[Service Account to Sync Custom Content]"
   

   Il comando assegna un indirizzo email per l'account di servizio nel seguente formato:

   [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

   Questo indirizzo email è obbligatorio nei comandi successivi.

5. Crea un file della chiave dell'account di servizio, sostituisci [KEY_FILE] con il nome file per la chiave:

   gcloud iam service-accounts keys create ~/[KEY_FILE] \
     --iam-account [SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com
   

6. Per concedere all'account di servizio l'accesso all'API con i contenuti personalizzati, esegui il comando seguente, sostituendo [YOUR_SERVICE_NAME] con il nome dell'API con i contenuti personalizzati:

   gcloud endpoints services add-iam-policy-binding [SERVICE-NAME] \
         --member=serviceAccount:[SERVICE_ACCOUNT_NAME]@[YOUR_PROJECT_ID].iam.gserviceaccount.com \
         --role roles/servicemanagement.configEditor
   

Inviare una richiesta per sincronizzare i contenuti personalizzati

I seguenti esempi mostrano come eseguire una richiesta di sincronizzazione di contenuti personalizzati. La richiesta deve essere simile alla seguente:

 POST https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content/

Sostituisci [YOUR_PROJECT_ID] e [YOUR_SERVICE_NAME] con i valori appropriati. Quando la richiesta viene completata correttamente, la risposta ha un codice di stato HTTP 200.

Gli esempi seguenti mostrano come recuperare un token di accesso dai server di autorizzazione di Google e utilizzarlo per effettuare la richiesta all'endpoint del portale utilizzando Python o la riga di comando:

Python

1. Installa le librerie Python richieste:

       pip install --upgrade google-auth

2. Per creare un oggetto Credentials dalle credenziali dell'account di servizio e dagli ambiti richiesti dall'endpoint ed effettuare la richiesta di sincronizzazione dei contenuti, sostituisci [YOUR_PROJECT_ID], /path/to/service.json e [YOUR_SERVICE_NAME] con i valori appropriati nello script seguente:

   from google.oauth2 import service_account
   from google.auth.transport.requests import AuthorizedSession
   
   SCOPES = ["https://www.googleapis.com/auth/service.management.readonly"]
   SERVICE_ACCOUNT_FILE = "/path/to/service.json"
   PROJECT_ID = "[YOUR_PROJECT_ID]"
   SERVICE_NAME = "[YOUR_SERVICE_NAME]"
   
   credentials = service_account.Credentials.from_service_account_file(
      SERVICE_ACCOUNT_FILE, scopes=SCOPES)
   authed_session = AuthorizedSession(credentials)
   endpoint =
   "https://endpointsportal.%s.cloud.goog/api/v1/%s/custom-content" % (PROJECT_ID, SERVICE_NAME)
   result = authed_session.post(endpoint)
   print result

Riga di comando

1. Apri Cloud Shell o apri una finestra del terminale se hai installato l'interfaccia a riga di comando gcloud sul tuo computer Linux.
2. Per eseguire l'autenticazione nel tuo account di servizio, sostituisci [KEY_FILE] di seguito con il percorso del file della chiave dell'account di servizio ed esegui il comando:

   gcloud auth activate-service-account --key-file [KEY_FILE]

3. Per ottenere un token di autorizzazione utilizzando il tuo account di servizio:

   ACCESS_TOKEN=$(gcloud auth print-access-token)

4. Quando chiami l'API, trasmetti il valore del token come token di connessione in un'intestazione di autorizzazione. Sostituisci [YOUR_PROJECT_ID] e [YOUR_SERVICE_NAME] con i valori appropriati:

   curl -X POST -H "Authorization: Bearer ${ACCESS_TOKEN}" \
   https://endpointsportal.[YOUR_PROJECT_ID].cloud.goog/api/v1/[YOUR_SERVICE_NAME]/custom-content