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

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

שליחת משוב

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

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

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

Data QnA API Conversational Analytics API השינוי הנדרש
נקודת קצה (endpoint) של dataqna.googleapis.com נקודת קצה (endpoint) של 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

השירות DataChatService ב-Conversational Analytics API לא משתמש באובייקט AgentConfig, שמשמש ב-Data QnA 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