Eseguire 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 Conversational Analytics (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 Conversational Analytics 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 Q&A e l'API Conversational Analytics ed elenca i passaggi necessari per la migrazione.

API Data QnA API Conversational Analytics Modifica obbligatoria
Endpoint dataqna.googleapis.com Endpoint geminidataanalytics.googleapis.com 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 ulteriori informazioni, vedi Sostituire 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 maggiori informazioni, vedi Aggiornare i riferimenti agli ID origine dati di Looker Studio.
AgentConfig oggetto ConversationOptions oggetto Sostituisci l'oggetto AgentConfig con l'oggetto ConversationOptions nelle tue richieste. Per saperne di più, vedi Abilitare 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 ulteriori informazioni, vedi Sostituire 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 progetto Google Cloud . Nell'API Conversational Analytics, il campo project è deprecato all'interno del messaggio ChatRequest. Utilizza invece il campo parent per specificare sia il progetto che 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 progetto Google Cloud .

Aggiornare i riferimenti agli ID origine dati di Looker Studio

Nell'API Data QnA, utilizzi il campo datasource_ids per fornire un elenco di ID origine dati di Looker Studio. Nell'API Conversational Analytics, utilizzi il campo studio_references per fornire un elenco di oggetti StudioDatasourceReference, ognuno dei quali contiene un singolo ID origine dati. Per saperne di più, consulta StudioDatasourceReferences.

Attiva l'analisi Python con ConversationOptions

L'oggetto AgentConfig, utilizzato nell'API Data Q&A per attivare gli strumenti, non viene utilizzato dal servizio DataChatService nell'API Conversational Analytics. Per attivare funzionalità come l'analisi Python nell'API Conversational Analytics, utilizza l'oggetto ConversationOptions quando crei o configuri un agente dati. 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 Conversational Analytics, 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

I seguenti esempi mostrano come adattare le richieste alla nuova struttura dell'API quando esegui la migrazione dall'API Data QnA all'API Conversational Analytics. 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 mostri 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 Conversational Analytics:

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 nel seguente modo:

  • 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 pubblici, 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 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/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 Conversational Analytics:

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 nel seguente modo:

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

Origine dati di 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 mostri 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 Conversational Analytics:

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 nel seguente modo:

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