מעבר מ-Data QnA API ל-Conversational Analytics API

במדריך הזה מפורטים ההבדלים העיקריים בין Data QnA API‏ (dataqna.googleapis.com) לבין Conversational Analytics API‏ (geminidataanalytics.googleapis.com), ומוסבר איך להעביר את האפליקציות שלכם מ-Data QnA API ל-Conversational Analytics API.

שליחת משוב

אם נתקלתם בחוסר התאמה במהלך תהליך ההעברה, אתם יכולים לפנות אל conversational-analytics-api-feedback@google.com.

סקירה כללית של השינויים העיקריים

ב-Conversational Analytics API יש שינויים בנקודת קצה ל-API, בשירות שבו ה-API משתמש ובמבנה של בקשות API. בטבלה הבאה מפורטים ההבדלים העיקריים בין Data QnA API לבין Conversational Analytics API, ומופיעים בה השלבים הנדרשים למעבר.

Data QnA API Conversational Analytics API השינוי הנדרש
dataqna.googleapis.com נקודת קצה geminidataanalytics.googleapis.com נקודת קצה מעדכנים את נקודת קצה ל-API בבקשות.
שירות DataQuestionService שירות DataChatService מעדכנים את שם השירות בבקשות.
השדה project בהודעה AskQuestionRequest השדה parent בהודעה ChatRequest מחליפים את השדה project בשדה parent בבקשות. מידע נוסף מופיע במאמר החלפת project ב-parent לניתוב בקשות.
שדה datasource_ids שדה studio_references מחליפים את השדה datasource_ids בשדה studio_references בבקשות. מידע נוסף זמין במאמר בנושא עדכון הפניות למזהי מקורות נתונים ב-Looker Studio.
אובייקט AgentConfig אובייקט ConversationOptions מחליפים את האובייקט AgentConfig באובייקט ConversationOptions בבקשות. מידע נוסף זמין במאמר הפעלת ניתוח Python באמצעות ConversationOptions.
השדה context בהודעה AskQuestionRequest השדה inline_context בהודעה ChatRequest מחליפים את השדה context בשדה inline_context בבקשות. מידע נוסף זמין במאמר החלפת context ב-inline_context.

דוגמאות לאופן העדכון של מבני בקשות ה-API מופיעות במאמר דוגמאות: עדכון של מבני בקשות ה-API.

החלפת project ב-parent לניתוב בקשות

ב-Data QnA API, משתמשים בשדה project בהודעה AskQuestionRequest כדי לציין את הפרויקט Google Cloud . ב-Conversational Analytics API, השדה project הוצא משימוש בהודעה ChatRequest. במקום זאת, משתמשים בשדה parent כדי לציין גם את הפרויקט וגם את המיקום.

בדוגמה הבאה אפשר לראות את הפורמט של השדה parent:

parent: "projects/your_project_name/locations/global"

בדוגמה הקודמת, מחליפים את your_project_name בשם הפרויקט. Google Cloud

עדכון הפניות למזהי מקורות נתונים ב-Looker Studio

ב-Data QnA API, משתמשים בשדה datasource_ids כדי לספק רשימה של מזהי מקורות נתונים של Looker Studio. ב-Conversational Analytics API, משתמשים בשדה studio_references כדי לספק רשימה של אובייקטים מסוג StudioDatasourceReference, שכל אחד מהם מכיל מזהה יחיד של מקור נתונים. מידע נוסף מופיע במאמר StudioDatasourceReferences.

הפעלת ניתוח Python באמצעות ConversationOptions

אובייקט AgentConfig, שמשמש ב-Data QnA API כדי להפעיל כלים, לא נמצא בשימוש בשירות DataChatService ב-Conversational Analytics API. כדי להפעיל תכונות כמו ניתוח Python ב-Conversational Analytics API, צריך להשתמש באובייקט ConversationOptions כשיוצרים או מגדירים סוכן נתונים. מידע נוסף זמין במאמר בנושא ConversationOptions.

מחליפים את context ב-inline_context

ב-Data QnA API, ההודעה AskQuestionRequest כוללת את השדה context למידע הקשרי מוטבע. ב-Conversational Analytics API, השם של השדה context משתנה ל-inline_context בהודעה ChatRequest. השינוי הזה עוזר להבחין בין הקשר בתוך הטקסט לבין סוגים אחרים של הקשר שאפשר לספק באמצעות סוכני נתונים.

דוגמאות: עדכון המבנים של בקשות ה-API

בדוגמאות הבאות מוצגות דרכים להתאים את הבקשות למבנה החדש של ה-API כשעוברים מ-Data QnA API ל-Conversational Analytics API. הדוגמאות האלה כוללות מקורות נתונים של BigQuery,‏ Looker ו-Looker Studio.

מקור נתונים ב-BigQuery

בקטע הזה מובאת דוגמה לאופן העדכון של בקשות API למקורות נתונים של BigQuery. בדוגמה מוצג איך לעדכן בקשה ליצירת תרשים עמודות שבו מוצגים חמשת המדינות עם המספר הכולל הגבוה ביותר של שדות תעופה.

דוגמת הקוד הבאה מציגה את מבנה הבקשה ל-Data QnA API:

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"
      }
    }
  }
}

בדוגמת הקוד הבאה מוצג המבנה המעודכן של הבקשה ל-Conversational Analytics API:

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"
      }
    }
  }

בדוגמאות הקודמות, אפשר להחליף את ערכי הדוגמה באופן הבא:

  • ‫your_project_name: השם של הפרויקט ב- Google Cloud .
  • ‫your_project_id: מזהה הפרויקט ב-BigQuery. כדי להתחבר למערך נתונים ציבורי, מציינים bigquery-public-data.
  • ‫your_dataset_id: המזהה של מערך הנתונים ב-BigQuery. לדוגמה, faa.
  • ‫your_table_id: המזהה של הטבלה ב-BigQuery. לדוגמה, us_airports.

מקור נתונים של Looker

בקטע הזה מופיעה דוגמה לאופן העדכון של בקשות API למקורות נתונים של Looker. בדוגמה הבאה אפשר לראות איך לעדכן בקשה לספירת ההזמנות לפי סטטוס ההזמנה.

דוגמת הקוד הבאה מציגה את מבנה הבקשה ל-Data QnA API:

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"
          }
        }
      }
    }
  }
}

בדוגמת הקוד הבאה מוצג המבנה המעודכן של הבקשה ל-Conversational Analytics API:

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"
          }
        }
      }
    }
  }
}

בדוגמאות הקודמות, אפשר להחליף את ערכי הדוגמה באופן הבא:

  • ‫your_project_name: השם של הפרויקט ב- Google Cloud
  • ‫https://your_company.looker.com: ה-URI של מופע Looker
  • ‫your_model: השם של מודל LookML
  • ‫your_explore: השם של LookML Explore
  • ‫your_looker_client_id: מזהה הלקוח של Looker
  • ‫your_looker_client_secret: סוד הלקוח של Looker

מקור נתונים ב-Looker Studio

בקטע הזה מופיעה דוגמה לאופן העדכון של בקשות ה-API למקורות נתונים ב-Looker Studio. בדוגמה הבאה מוצג איך לעדכן בקשה ליצירת תרשים עמודות שבו מוצגות חמש חברות התעופה המובילות.

דוגמת הקוד הבאה מציגה את מבנה הבקשה ל-Data QnA API:

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"
    }
  }
}

בדוגמת הקוד הבאה מוצג המבנה המעודכן של הבקשה ל-Conversational Analytics API:

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"
    }
  }
}

בדוגמאות הקודמות, אפשר להחליף את ערכי הדוגמה באופן הבא:

  • ‫your_project_name: השם של הפרויקט ב- Google Cloud
  • ‫your_data_source_id: המזהה של מקור הנתונים של Looker Studio