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

Questa guida descrive le principali differenze e i passaggi per 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 la procedura 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 riepiloga 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 richiesta
Endpoint dataqna.googleapis.com Endpoint geminidataanalytics.googleapis.com Aggiorna l'endpoint API nelle richieste.
Servizio DataQuestionService Servizio DataChatService Aggiorna il nome del servizio nelle richieste.
Campo project nel messaggio AskQuestionRequest Campo parent nel messaggio ChatRequest Sostituisci il campo project con il campo parent nelle richieste. Per ulteriori informazioni, 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 richieste. Per ulteriori informazioni, consulta Aggiorna i riferimenti agli ID delle origini dati di Looker Studio.
Oggetto AgentConfig Oggetto ConversationOptions Sostituisci l'oggetto AgentConfig con l'oggetto ConversationOptions nelle richieste. Per ulteriori informazioni, 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 richieste. Per ulteriori informazioni, consulta Sostituisci context con inline_context.

Per esempi di 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, utilizzi il campo project all'interno del messaggio AskQuestionRequest per specificare il Google Cloud progetto. Nell'API Analisi conversazionale, il campo project è deprecato all'interno del messaggio ChatRequest. Invece, utilizzi il campo parent per specificare sia il progetto sia la località.

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

parent: "projects/your_project_name/locations/global"

Nell'esempio precedente, sostituisci your_project_name con il nome del tuo Google Cloud progetto.

Aggiorna i riferimenti agli ID delle origini dati di Looker Studio

Nell'API Data QnA, utilizzi il campo datasource_ids per fornire un elenco di ID delle origini dati di Looker Studio. Nell'API Analisi conversazionale, utilizzi il campo studio_references per fornire un elenco di oggetti StudioDatasourceReference, ognuno dei quali contiene un singolo ID origine dati. Per ulteriori informazioni, consulta StudioDatasourceReferences.

Abilita l'analisi Python con ConversationOptions

L'oggetto AgentConfig, utilizzato nell'API Data QnA per abilitare gli strumenti, non viene utilizzato dal servizio DataChatService nell'API Analisi conversazionale. Per abilitare funzionalità come l'analisi Python nell'API Analisi conversazionale, utilizza l'oggetto ConversationOptions quando crei o configuri un agente dati. Per ulteriori informazioni, 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 consente di distinguere il contesto in linea da altri tipi di contesto che possono essere forniti tramite gli agenti dati.

Esempi: aggiorna le strutture delle richieste API

Gli esempi seguenti 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 Looker 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/your_project_name"
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: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_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/your_project_name/locations/global"
inline_context {
  datasource_references {
    bq {
      table_references {
        project_id: "your_project_id"
        dataset_id: "your_dataset_id"
        table_id: "your_table_id"
      }
    }
  }

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

  • your_project_name: il nome del tuo Google Cloud progetto.
  • your_project_id: l'ID del tuo progetto BigQuery. Per connetterti a un set di dati pubblico, specifica bigquery-public-data.
  • your_dataset_id: l'ID del set di dati BigQuery. Ad esempio, faa.
  • your_table_id: l'ID della tabella BigQuery. Ad esempio, us_airports.

Origine dati Looker

Questa sezione fornisce un esempio di come aggiornare le richieste API per le origini dati 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/your_project_name"
messages {
  user_message {
    text: "Show the count of orders by order status."
  }
}
context {
  datasource_references {
    looker {
      explore_references {
        looker_instance_uri: "https://your_company.looker.com"
        lookml_model: "your_model"
        explore: "your_explore"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_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/your_project_name/locations/global"
inline_context {
  datasource_references {
    looker {
      explore_references {
        lookml_model: "your_model"
        explore: "your_explore"
        looker_instance_uri: "https://your_company.looker.com"
      }
      credentials {
        oauth {
          secret {
            client_id: "your_looker_client_id"
            client_secret: "your_looker_client_secret"
          }
        }
      }
    }
  }
}

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

  • your_project_name: il nome del tuo Google Cloud progetto
  • https://your_company.looker.com: l'URI della tua istanza Looker
  • your_model: il nome del tuo modello LookML
  • your_explore: il nome della tua esplorazione LookML
  • your_looker_client_id: il tuo ID client Looker
  • your_looker_client_secret: il tuo client secret Looker

Origine dati Looker Studio

Questa sezione fornisce un esempio di come aggiornare le richieste API per le origini dati di Looker Studio. L'esempio mostra come aggiornare una richiesta che chiede 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/your_project_name"
messages {
  user_message {
    text: "Create a bar graph showing the top 5 carriers."
  }
}
context {
  datasource_references {
    studio {
      datasource_ids: "your_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/your_project_name/locations/global"
inline_context {
  datasource_references {
    studio {
      datasource_ids: "your_data_source_id"
    }
  }
}

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

  • your_project_name: il nome del tuo Google Cloud progetto
  • your_data_source_id: l'ID della tua origine dati di Looker Studio