- בקשת HTTP
- פרמטרים של הנתיב
- גוף הבקשה
- גוף התגובה
- היקפי הרשאות
- QueryDataContext
- ParameterizedSecureViewParameters
- פרמטר
- GenerationOptions
- ExecutedQueryResult
- עמודה
- שורה
- ערך
- TokenUsage
שליפת נתונים משאילתה של משתמש בשפה טבעית.
בקשת HTTP
POST https://geminidataanalytics.googleapis.com/v1alpha/{parent=projects/*/locations/*}:queryData
כתובת ה-URL כתובה בתחביר של gRPC Transcoding.
פרמטרים של הנתיב
| פרמטרים | |
|---|---|
parent |
חובה. משאב ההורה שעבורו נוצרת השאילתה. פורמט: projects/{project}/locations/{location} |
גוף הבקשה
גוף הבקשה מכיל נתונים במבנה הבא:
| ייצוג ב-JSON |
|---|
{ "prompt": string, "context": { object ( |
| שדות | |
|---|---|
prompt |
חובה. השאילתה בשפה טבעית שעבורה רוצים ליצור שאילתה. דוגמה: "מהם 5 המוצרים הכי נמכרים החודש?" |
context |
חובה. ההקשר של שאילתת הנתונים, כולל מקורות הנתונים שבהם צריך להשתמש. |
generationOptions |
זה שינוי אופציונלי. אפשרויות לשליטה בהתנהגות של יצירת שאילתות והרצת שאילתות. |
גוף התשובה
תשובה שמכילה את השאילתה שנוצרה ומידע קשור.
אם הפעולה מצליחה, גוף התשובה מכיל נתונים במבנה הבא:
| ייצוג ב-JSON |
|---|
{ "generatedQuery": string, "intentExplanation": string, "queryResult": { object ( |
| שדות | |
|---|---|
generatedQuery |
השאילתה שנוצרה לפי הנחיית המשתמש. |
intentExplanation |
הסבר בשפה טבעית על השאילתה שנוצרה. מאוכלס אם options.generate_explanation היה true בבקשה. |
queryResult |
התוצאה של הרצת השאילתה. השדה מאוכלס אם הערך של options.generate_query_result או options.generate_natural_language_answer היה true בבקשה, והביצוע הצליח או בוצע ניסיון לבצע אותו. |
naturalLanguageAnswer |
תשובה בשפה טבעית לשאילתה, על סמך queryResult. השדה הזה מאוכלס אם הערך של options.generate_natural_language_answer היה true בבקשה, והשאילתה בוצעה בהצלחה על סמך התגובה מ-executeSql API. |
disambiguationQuestion[] |
אם זוהתה עמימות בשאילתה בשפה טבעית והערך של options.generate_disambiguation_question היה true, השדה הזה מכיל שאלה למשתמש לצורך הבהרה. התוצאה שהתקבלה מייצגת את הניסיון הטוב ביותר של השירות על סמך הקלט הלא ברור. |
pipelineDebugInfo |
מידע מפורט על הרצת צינור עיבוד נתונים, שלב אחרי שלב. השדה הזה מאוכלס רק אם הערך של generationOptions.generate_debug_info היה True. המידע הזה מיועד למטרות ניפוי באגים ושקיפות בלבד. המבנה והתוכן של האובייקט הזה לא מובטחים, והם עשויים להשתנות בכל שלב בלי הודעה מוקדמת. אל תכתבו קוד ייצור או לוגיקה עסקית שתלויים בשדות באובייקט הזה. |
tokenUsage |
השימוש הכולל בטוקנים לבקשה. |
היקפי הרשאות
צריך אחד מהיקפי ההרשאות הבאים של OAuth:
https://www.googleapis.com/auth/cloud-platformhttps://www.googleapis.com/auth/geminidataanalytics
ניתן למצוא מידע נוסף כאן: Authentication Overview.
QueryDataContext
הפניות למקורות נתונים ולהקשר שבהם צריך להשתמש בשאילתה.
| ייצוג ב-JSON |
|---|
{ "datasourceReferences": { object ( |
| שדות | |
|---|---|
datasourceReferences |
חובה. ההפניות למקור הנתונים שבהן צריך להשתמש בשאילתה. |
parameterizedSecureViewParameters |
זה שינוי אופציונלי. פרמטרים לתצוגות מאובטחות עם פרמטרים (PSV). |
ParameterizedSecureViewParameters
פרמטרים לתצוגות מאובטחות עם פרמטרים (PSV). הפרמטרים האלה משמשים לאכיפת אבטחה ברמת השורה במהלך יצירת SQL והרצת שאילתות.
| ייצוג ב-JSON |
|---|
{
"parameters": [
{
object ( |
| שדות | |
|---|---|
parameters[] |
זה שינוי אופציונלי. פרמטרים עם שמות לתצוגות מאובטחות עם פרמטרים (PSV). |
פרמטר
מייצג פרמטר יחיד לתצוגות מאובטחות עם פרמטרים.
| ייצוג ב-JSON |
|---|
{ "key": string, "value": string } |
| שדות | |
|---|---|
key |
חובה. מפתח הפרמטר (למשל, |
value |
חובה. ערך הפרמטר (למשל, |
GenerationOptions
אפשרויות לשליטה ביצירת השאילתות, בהרצה שלהן ובפורמט התשובה.
| ייצוג ב-JSON |
|---|
{ "generateQueryResult": boolean, "generateNaturalLanguageAnswer": boolean, "generateExplanation": boolean, "generateDisambiguationQuestion": boolean, "generateDebugInfo": boolean } |
| שדות | |
|---|---|
generateQueryResult |
זה שינוי אופציונלי. אם הערך הוא true, השאילתה שנוצרה תופעל ונתוני התוצאה יוחזרו בתגובה. |
generateNaturalLanguageAnswer |
זה שינוי אופציונלי. אם הערך הוא true, תיווצר תשובה בשפה טבעית על סמך תוצאת הרצת השאילתה, והיא תוחזר בתגובה. |
generateExplanation |
זה שינוי אופציונלי. אם הערך הוא True, התשובה תכלול הסבר על השאילתה שנוצרה. |
generateDisambiguationQuestion |
זה שינוי אופציונלי. אם הערך הוא True (ברירת המחדל היא False), השירות עשוי להחזיר clarifying_question אם שאילתת הקלט לא ברורה. |
generateDebugInfo |
זה שינוי אופציונלי. אם הערך הוא True (ברירת המחדל היא False), הפונקציה מחזירה מידע פנימי על תוצאות ניפוי הבאגים. |
ExecutedQueryResult
התוצאה של הרצת שאילתה. העיצוב הוא כללי לכל הניבים.
| ייצוג ב-JSON |
|---|
{ "columns": [ { object ( |
| שדות | |
|---|---|
columns[] |
העמודות בקבוצת התוצאות, לפי הסדר. |
rows[] |
השורות שהוחזרו על ידי השאילתה. |
totalRowCount |
המספר הכולל של השורות בקבוצת התוצאות המלאה, אם הוא ידוע. המספר הזה יכול להיות אומדן או ספירה מדויקת. הערה: אם הופעלה מגבלה פנימית (כמו LIMIT 1000) במהלך הרצת השאילתה כדי למנוע העברת נתונים מוגזמת, המספר הזה משקף את גודל התוצאה המקוצרת ולא את גודל התוצאה של הטבלה הלא מוגבלת. |
partialResult |
צריך להגדיר את הערך כ-true אם השורות שמוחזרות ב- |
queryExecutionError |
הודעת השגיאה שמוצגת אם הרצת השאילתה נכשלה. |
עמודה
מתאר עמודה אחת בקבוצת התוצאות.
| ייצוג ב-JSON |
|---|
{ "name": string, "type": string } |
| שדות | |
|---|---|
name |
שם העמודה. |
type |
סוג העמודה (למשל, VARCHAR, INT64, TIMESTAMP). |
Row
מייצג שורה אחת בקבוצת התוצאות.
| ייצוג ב-JSON |
|---|
{
"values": [
{
object ( |
| שדות | |
|---|---|
values[] |
הערכים בשורה, בהתאם למיקום של העמודות. |
ערך
מייצג ערך יחיד בתוך שורה.
| ייצוג ב-JSON |
|---|
{ "value": string } |
| שדות | |
|---|---|
value |
ערך התא, מיוצג בפורמט של מחרוזת. אפשר להגדיר את הפורמט של חותמות הזמן, למשל באמצעות RFC3339Nano. המערכת משתמשת בשדה הזה אם הערך הוא לא null. |
TokenUsage
מעקב אחרי השימוש הכולל בטוקנים לבקשה.
| ייצוג ב-JSON |
|---|
{ "inputTokenCount": integer, "outputTokenCount": integer } |
| שדות | |
|---|---|
inputTokenCount |
המספר הכולל של טוקנים של קלט שנעשה בהם שימוש בבקשה הזו. |
outputTokenCount |
המספר הכולל של טוקני הפלט שנעשה בהם שימוש בבקשה הזו. |