Method: projects.locations.queryData

שליפת נתונים משאילתת משתמש בשפה טבעית.

בקשת HTTP

POST https://geminidataanalytics.googleapis.com/v1beta/{parent=projects/*/locations/*}:queryData

כתובת ה-URL כתובה בתחביר של gRPC Transcoding.

פרמטרים של נתיב

פרמטרים
parent

string

חובה. משאב האב ליצירת השאילתה. הפורמט: projects/{project}/locations/{location}

גוף הבקשה

גוף הבקשה מכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "prompt": string,
  "context": {
    object (QueryDataContext)
  },
  "generationOptions": {
    object (GenerationOptions)
  }
}
שדות
prompt

string

חובה. השאילתה בשפה טבעית שעבורה רוצים ליצור שאילתה. דוגמה: "מהם 5 המוצרים הכי נמכרים החודש?"
context

object (QueryDataContext)

חובה. ההקשר של שאילתת הנתונים, כולל מקורות הנתונים שבהם צריך להשתמש.
generationOptions

object (GenerationOptions)

זה שינוי אופציונלי. אפשרויות לשליטה בהתנהגות של יצירת שאילתות והרצת שאילתות.

גוף התשובה

תשובה שמכילה את השאילתה שנוצרה ומידע קשור.

אם הפעולה בוצעה ללא שגיאות, גוף התגובה יכיל נתונים במבנה הבא:

ייצוג ב-JSON 
{
  "generatedQuery": string,
  "intentExplanation": string,
  "queryResult": {
    object (ExecutedQueryResult)
  },
  "naturalLanguageAnswer": string,
  "disambiguationQuestion": [
    string
  ]
}
שדות
generatedQuery

string

שאילתה שנוצרה להנחיה שניתנה על ידי המשתמש.
intentExplanation

string

הסבר בשפה טבעית על השאילתה שנוצרה. מאוכלס אם הערך של options.generate_explanation היה true בבקשה.
queryResult

object (ExecutedQueryResult)

התוצאה של הפעלת השאילתה. השדה הזה מאוכלס אם הערך של options.generate_query_result או של options.generate_natural_language_answer היה true בבקשה, והביצוע היה מוצלח או שהיה ניסיון לבצע אותו.
naturalLanguageAnswer

string

תשובה לשאילתה בשפה טבעית, על סמך queryResult. מאוכלס אם הערך של options.generate_natural_language_answer היה true בבקשה והרצת השאילתה הצליחה על סמך התגובה מ-executeSql API.
disambiguationQuestion[]

string

אם זוהתה דו-משמעות בשאילתת השפה הטבעית והאפשרות generate_disambiguation_question הייתה true, השדה הזה מכיל שאלה למשתמש להבהרה. התוצאה שמוחזרת מייצגת את המאמץ הכי טוב של השירות על סמך הקלט הלא חד-משמעי.

היקפי הרשאות

נדרש היקף ההרשאות הבא של OAuth:

  • https://www.googleapis.com/auth/cloud-platform

ניתן למצוא מידע נוסף כאן: Authentication Overview.

QueryDataContext

הפניות למקורות נתונים ולהקשר לשימוש בשאילתה.

ייצוג ב-JSON 
{
  "datasourceReferences": {
    object (DatasourceReferences)
  },
  "parameterizedSecureViewParameters": {
    object (ParameterizedSecureViewParameters)
  }
}
שדות
datasourceReferences

object (DatasourceReferences)

חובה. הפניות למקור הנתונים שבהן רוצים להשתמש בשאילתה.
parameterizedSecureViewParameters

object (ParameterizedSecureViewParameters)

זה שינוי אופציונלי. פרמטרים לתצוגות מאובטחות עם פרמטרים.

ParameterizedSecureViewParameters

פרמטרים לתצוגות מאובטחות עם פרמטרים. הפרמטרים האלה משמשים לאכיפת אבטחה ברמת השורה במהלך יצירת SQL והרצת שאילתות.

ייצוג ב-JSON 
{
  "parameters": [
    {
      object (Parameter)
    }
  ]
}
שדות
parameters[]

object (Parameter)

זה שינוי אופציונלי. פרמטרים עם שמות לתצוגות מאובטחות עם פרמטרים.

פרמטר

מייצג פרמטר יחיד לתצוגות מאובטחות עם פרמטרים.

ייצוג ב-JSON 
{
  "key": string,
  "value": string
}
שדות
key

string

חובה. מפתח הפרמטר (למשל, "userId").
value

string

חובה. ערך הפרמטר (למשל, "123").

GenerationOptions

אפשרויות לשליטה ביצירת השאילתה, בהרצה שלה ובפורמט התשובה.

ייצוג ב-JSON 
{
  "generateQueryResult": boolean,
  "generateNaturalLanguageAnswer": boolean,
  "generateExplanation": boolean,
  "generateDisambiguationQuestion": boolean
}
שדות
generateQueryResult

boolean

זה שינוי אופציונלי. אם הערך הוא true, השאילתה שנוצרה תופעל ונתוני התוצאה יוחזרו בתגובה.
generateNaturalLanguageAnswer

boolean

זה שינוי אופציונלי. אם הערך הוא true, תיווצר תשובה בשפה טבעית על סמך תוצאת הביצוע של השאילתה, והיא תוחזר בתגובה.
generateExplanation

boolean

זה שינוי אופציונלי. אם הערך הוא true, הסבר על השאילתה שנוצרה יוחזר בתשובה.
generateDisambiguationQuestion

boolean

זה שינוי אופציונלי. אם הערך הוא true (ברירת המחדל היא false), השירות עשוי להחזיר שאלה להבהרה אם שאילתת הקלט לא ברורה.

ExecutedQueryResult

התוצאה של ביצוע שאילתה. העיצוב הוא כללי ומתאים לכל הניבים.

ייצוג ב-JSON 
{
  "columns": [
    {
      object (Column)
    }
  ],
  "rows": [
    {
      object (Row)
    }
  ],
  "totalRowCount": string,
  "partialResult": boolean,
  "queryExecutionError": string
}
שדות
columns[]

object (Column)

העמודות בקבוצת התוצאות, לפי הסדר.
rows[]

object (Row)

השורות שמוחזרות על ידי השאילתה.
totalRowCount

string (int64 format)

המספר הכולל של השורות בקבוצת התוצאות המלאה, אם ידוע. יכול להיות שזה יהיה אומדן או מספר מדויק.
partialResult

boolean

הערך מוגדר כ-true אם השורות שמוחזרות בפונקציה queryResult הן קבוצת משנה של התוצאה המלאה. לדוגמה, מצב כזה יכול לקרות אם הביצוע של השאילתה מגיע למגבלת השורות. אם הערך הוא True, ה-queryResult לא מכיל את כל השורות. כדי לאחזר את התוצאה המלאה, כדאי להשתמש בפונקציה generatedQuery ב-QueryDataResponse ולהריץ אותה בסביבה שלכם.
queryExecutionError

string

הודעת השגיאה אם ביצוע השאילתה נכשל.

עמודה

מתארת עמודה אחת בערכת התוצאות.

ייצוג ב-JSON 
{
  "name": string,
  "type": string
}
שדות
name

string

שם העמודה.
type

string

סוג העמודה (לדוגמה, VARCHAR,‏ INT64,‏ TIMESTAMP).

Row

מייצג שורה אחת בערכת התוצאות.

ייצוג ב-JSON 
{
  "values": [
    {
      object (Value)
    }
  ]
}
שדות
values[]

object (Value)

הערכים בשורה, בהתאמה לעמודות.

ערך

מייצג ערך יחיד בשורה.

ייצוג ב-JSON 
{
  "value": string
}
שדות
value

string

הערך של התא, שמוצג בפורמט מחרוזת. אפשר לעצב את חותמות הזמן, למשל באמצעות RFC3339Nano. השדה הזה נמצא בשימוש אם הערך הוא לא null.