Esegui la migrazione dall'API Data QnA all'API Conversational Analytics

Questa guida descrive le differenze principali e i passaggi per eseguire la migrazione delle applicazioni dall'API Data QnA (dataqna.googleapis.com) all'API Analisi conversazionale (geminidataanalytics.googleapis.com).

Invia il tuo feedback

Se riscontri discrepanze durante il processo di migrazione, contatta conversational-analytics-api-feedback@google.com.

Panoramica delle modifiche principali

L'API Analisi conversazionale introduce modifiche all'endpoint API, al servizio utilizzato dall'API e alla struttura delle richieste API. La seguente tabella riassume le principali differenze tra l'API Data QnA e l'API Analisi conversazionale ed elenca i passaggi necessari per la migrazione.

API Data QnA API di Analisi conversazionale Modifica obbligatoria
dataqna.googleapis.com endpoint geminidataanalytics.googleapis.com endpoint Aggiorna l'endpoint API nelle tue richieste.
Servizio DataQuestionService Servizio DataChatService Aggiorna il nome del servizio nelle tue richieste.
Campo project nel messaggio AskQuestionRequest Campo parent nel messaggio ChatRequest Sostituisci il campo project con il campo parent nelle tue richieste. Per saperne di più, consulta Sostituisci project con parent per il routing delle richieste.
Campo datasource_ids Campo studio_references Sostituisci il campo datasource_ids con il campo studio_references nelle tue richieste. Per saperne di più, consulta Aggiorna i riferimenti agli ID origine dati di Data Studio.
AgentConfig oggetto ConversationOptions oggetto Sostituisci l'oggetto AgentConfig con l'oggetto ConversationOptions nelle tue richieste. Per saperne di più, consulta Abilita l'analisi Python con ConversationOptions.
Campo context nel messaggio AskQuestionRequest Campo inline_context nel messaggio ChatRequest Sostituisci il campo context con il campo inline_context nelle tue richieste. Per saperne di più, consulta Sostituisci context con inline_context.

Per esempi su come aggiornare le strutture delle richieste API, consulta Esempi: aggiorna le strutture delle richieste API.

Sostituisci project con parent per il routing delle richieste

Nell'API Data QnA, utilizza il campo project all'interno del messaggio AskQuestionRequest per specificare il progetto Google Cloud . Nell'API Analisi conversazionale, il campo project è deprecato all'interno del messaggio ChatRequest. Utilizza invece il campo parent per specificare sia il progetto sia la località.

L'esempio seguente mostra il formato per specificare il campo parent:

parent: "projects/BILLING_PROJECT/locations/global"

Nell'esempio precedente, sostituisci BILLING_PROJECT con l'ID del tuo progetto di fatturazione.

Aggiorna i riferimenti agli ID delle origini dati di Data Studio

Nell'API Data QnA, utilizzi il campo datasource_ids per fornire un elenco di ID origine dati di Data Studio. Nell'API Analisi conversazionale, utilizzi il campo studio_references per fornire un elenco di oggetti StudioDatasourceReference, ciascuno contenente un singolo ID origine dati. Per saperne di più, consulta StudioDatasourceReference.

Attiva l'analisi Python con ConversationOptions

L'oggetto AgentConfig, utilizzato nell'API Data QnA per attivare gli strumenti, non viene utilizzato dal servizio DataChatService nell'API Analisi conversazionale. Per attivare funzionalità come l'analisi Python nell'API Analisi conversazionale, utilizza l'oggetto ConversationOptions quando crei o configuri un agente per i dati. L'analisi Python non è supportata per le origini dati BigQuery. Per saperne di più, consulta ConversationOptions.

Sostituisci context con inline_context

Nell'API Data QnA, il messaggio AskQuestionRequest include un campo context per le informazioni contestuali in linea. Nell'API Analisi conversazionale, il campo context viene rinominato in inline_context nel messaggio ChatRequest. Questa modifica aiuta a distinguere il contesto incorporato da altri tipi di contesto che possono essere forniti tramite gli agenti per i dati.

Esempi: aggiorna le strutture delle richieste API

I seguenti esempi mostrano come adattare le richieste alla nuova struttura dell'API quando esegui la migrazione dall'API Data QnA all'API Analisi conversazionale. Questi esempi riguardano le origini dati BigQuery, Looker e Data Studio.

Origine dati BigQuery

Questa sezione fornisce un esempio di come aggiornare le richieste API per le origini dati BigQuery. L'esempio mostra come aggiornare una richiesta che chiede un grafico a barre che mostra i primi cinque stati in base al numero totale di aeroporti.

Il seguente esempio di codice mostra la struttura della richiesta per l'API Data QnA:

project: "projects/BILLING_PROJECT"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
context {
  datasource_references {
    bq {
      table_references {
        project_id: "PROJECT_ID"
        dataset_id: "DATASET_ID"
        table_id: "TABLE_ID"
      }
    }
  }
}

Il seguente esempio di codice mostra la struttura della richiesta aggiornata per l'API Analisi conversazionale:

messages {
  user_message {
    text: "Create a bar graph showing the top 5 states by the total number of airports."
  }
}
parent: "projects/BILLING_PROJECT/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "PROJECT_ID"
        dataset_id: "DATASET_ID"
        table_id: "TABLE_ID"
      }
    }
  }
}

Per gli esempi precedenti, puoi sostituire i valori di esempio come segue:

  • BILLING_PROJECT: l'ID del progetto di fatturazione.
  • PROJECT_ID: l'ID del tuo progetto BigQuery. Per connetterti a un set di dati pubblico, specifica bigquery-public-data.
  • DATASET_ID: l'ID del set di dati BigQuery. Ad esempio, faa.
  • TABLE_ID: l'ID della tabella BigQuery. Ad esempio, us_airports.

Origine dati di Looker

Questa sezione fornisce un esempio di come aggiornare le richieste API per le origini dati di Looker. L'esempio mostra come aggiornare una richiesta che chiede il conteggio degli ordini in base allo stato dell'ordine.

Il seguente esempio di codice mostra la struttura della richiesta per l'API Data QnA:

project: "projects/BILLING_PROJECT"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "INSTANCE_URI"
        lookml_model: "MODEL_NAME"
        explore: "EXPLORE_NAME"
      }
      credentials {
        oauth {
          secret {
            client_id: "CLIENT_ID"
            client_secret: "CLIENT_SECRET"
          }
        }
      }
    }
  }
}

Il seguente esempio di codice mostra la struttura della richiesta aggiornata per l'API Analisi conversazionale:

messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
parent: "projects/BILLING_PROJECT/locations/global"
credentials {
  oauth {
    secret {
      client_id: "CLIENT_ID"
      client_secret: "CLIENT_SECRET"
    }
  }
}
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "MODEL_NAME"
        explore: "EXPLORE_NAME"
        looker_instance_uri: "INSTANCE_URI"
      }
    }
  }
}

Per gli esempi precedenti, puoi sostituire i valori di esempio come segue:

  • BILLING_PROJECT: l'ID del progetto di fatturazione.
  • CLIENT_ID: l'ID client della chiave API Looker generata.
  • CLIENT_SECRET: il client secret della chiave API Looker generata.
  • MODEL_NAME: il nome del modello LookML.
  • EXPLORE_NAME: il nome dell'esplorazione LookML.
  • INSTANCE_URI: l'URI dell'istanza di Looker.

Origine dati di Data Studio

Questa sezione fornisce un esempio di come aggiornare le richieste API per le origini dati di Data Studio. L'esempio mostra come aggiornare una richiesta che richiede un grafico a barre che mostra i primi cinque corrieri.

Il seguente esempio di codice mostra la struttura della richiesta per l'API Data QnA:

project: "projects/BILLING_PROJECT"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
context {
  datasource_references {
    studio {
      datasource_ids: "DATA_SOURCE_ID"
    }
  }
}

Il seguente esempio di codice mostra la struttura della richiesta aggiornata per l'API Analisi conversazionale:

messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
parent: "projects/BILLING_PROJECT/locations/global"
inline_context {
  datasource_references {
    studio {
      studio_references {
        datasource_id: "DATA_SOURCE_ID"
      }
    }
  }
}

Per gli esempi precedenti, puoi sostituire i valori di esempio come segue:

  • BILLING_PROJECT: l'ID del progetto di fatturazione.
  • DATA_SOURCE_ID: l'ID dell'origine dati di Data Studio.