获取应用列表接口升级 (baidubce#568)

* 获取应用列表接口升级

appbuilder/__init__.py

@@ -176,7 +176,7 @@ def get_default_header():
 
 from appbuilder.core.console.appbuilder_client.appbuilder_client import AppBuilderClient
 from appbuilder.core.console.appbuilder_client.appbuilder_client import AgentBuilder
-from appbuilder.core.console.appbuilder_client.appbuilder_client import get_app_list, get_all_apps
+from appbuilder.core.console.appbuilder_client.appbuilder_client import get_app_list, get_all_apps, describe_apps
 from appbuilder.core.console.knowledge_base.knowledge_base import KnowledgeBase
 from appbuilder.core.console.knowledge_base.data_class import CustomProcessRule, DocumentSource, DocumentChoices, DocumentChunker, DocumentSeparator, DocumentPattern, DocumentProcessOption
 
@@ -215,6 +215,7 @@ def get_default_header():
     "AgentBuilder",
     "get_app_list",
     "get_all_apps",
+    "describe_apps",
     "KnowledgeBase",
     "CustomProcessRule",
     "DocumentSource",

appbuilder/core/console/__init__.py

@@ -15,6 +15,6 @@
 from .dataset import Dataset
 from .rag import RAG
 from .appbuilder_client import AppBuilderClient
-from .appbuilder_client import get_app_list
+from .appbuilder_client import get_app_list, describe_apps
 from .knowledge_base import KnowledgeBase
 from .knowledge_base import CustomProcessRule

appbuilder/core/console/appbuilder_client/__init__.py

@@ -13,4 +13,4 @@
 # limitations under the License.
 
 from .appbuilder_client import AppBuilderClient
-from .appbuilder_client import get_app_list
+from .appbuilder_client import get_app_list, describe_apps

appbuilder/core/console/appbuilder_client/appbuilder_client.py

@@ -26,7 +26,7 @@
 from appbuilder.utils.logger_util import logger
 from appbuilder.utils.trace.tracer_wrapper import client_run_trace, client_tool_trace
 
-
+@deprecated(reason="use describe_apps instead")
 @client_tool_trace
 def get_app_list(
     limit: int = 10,
@@ -72,6 +72,45 @@ def get_app_list(
     out = resp.data
     return out
 
+@client_tool_trace
+def describe_apps(
+    marker: Optional[str]=None, 
+    maxKeys: int=10,
+    secret_key: Optional[str] = None,
+    gateway: Optional[str] = None
+)-> list[data_class.AppOverview]:
+    """
+    该接口查询用户下状态为已发布的应用列表
+
+    Args:
+        maxKeys (int, optional): 返回结果的最大数量，默认值为10，最大为100。
+        marker (str, optional): 起始位置，即从哪个游标开始查询，默认值为空字符串。
+        secret_key (Optional[str], optional): 认证密钥。如果未指定，则使用默认的密钥。默认值为None。
+        gateway (Optional[str], optional): 网关地址。如果未指定，则使用默认的地址。默认值为None。
+
+    Returns:
+        DescribeAppsResponse: 应用列表。
+
+    """
+    client = HTTPClient(secret_key=secret_key, gateway_v2=gateway)
+    headers = client.auth_header_v2()
+    headers["Content-Type"] = "application/json"
+    url = client.service_url_v2("/app?Action=DescribeApps")
+    request = data_class.DescribeAppsRequest(
+        MaxKeys=maxKeys, Marker=marker
+    )
+    response = client.session.post(
+        url=url,
+        json=request.model_dump(),
+        headers=headers,
+    )
+
+    client.check_response_header(response)
+    data = response.json()
+    resp = data_class.DescribeAppsResponse(**data)
+    out = resp.data
+    return out
+
 
 @client_tool_trace
 def get_all_apps():
@@ -87,13 +126,13 @@ def get_all_apps():
 
     """
     app_list = []
-    response_per_time = get_app_list(limit=100)
+    response_per_time = describe_apps(maxKeys=100)
     list_len_per_time = len(response_per_time)
     if list_len_per_time != 0:
         app_list.extend(response_per_time)
     while list_len_per_time == 100:
         after_id = response_per_time[-1].id
-        response_per_time = get_app_list(after=after_id, limit=100)
+        response_per_time = describe_apps(marker=after_id, maxKeys=100)
         list_len_per_time = len(response_per_time)
         if list_len_per_time != 0:
             app_list.extend(response_per_time)

appbuilder/core/console/appbuilder_client/data_class.py

@@ -305,8 +305,26 @@ class AppOverview(BaseModel):
     id: str = Field("", description="应用ID")
     name: str = Field("", description="应用名称")
     description: str = Field("", description="应用简介")
+    appType: Optional[str] = Field(
+        None,
+        description="应用类型:agent、chatflow。agent:自主规划Agent, chatflow:工作流Agent。"
+    )
+    isPublished: Optional[bool] = Field(None, description="是否已发布")
+    updateTime: Optional[int] = Field(None, description="更新时间。时间戳，单位秒")
 
 class AppBuilderClientAppListResponse(BaseModel):
     request_id: str = Field("", description="请求ID")
     data: Optional[list[AppOverview]] = Field(
         [], description="应用概览列表")
+
+class DescribeAppsRequest(BaseModel):
+    maxKeys: int = Field(default=10, description="当次查询的数据大小，默认10，最大值100", le=100, ge=1)
+    marker: str = Field(default=None, description="用于分页的游标。marker 是应用的id，它定义了在列表中的位置。例如，如果你发出一个列表请求并收到 10个对象，以 app_id_123 开始，那么可以使用 marker=app_id_123 来获取列表的下一页数据")
+
+class DescribeAppsResponse(BaseModel):
+    requestId: str = Field("", description="请求ID")
+    marker: str = Field("", description="起始位置")
+    isTruncated: bool = Field(False, description="是否有更多数据")
+    nextMarker: str = Field("", description="下一次起始位置")
+    maxKeys: int = Field(0, description="最大返回数量")
+    data: list[AppOverview] = Field([], description="应用概览列表")

appbuilder/tests/test_appbuilder_client_app_list.py

@@ -13,17 +13,26 @@
 # limitations under the License.
 
 import unittest
-import requests
 import appbuilder
 import os
-import logging
 
 @unittest.skipUnless(os.getenv("TEST_CASE", "UNKNOWN") == "CPU_SERIAL","")
 class TestGetAppList(unittest.TestCase):
     def test_get_app_list_v1(self):
         app_list = appbuilder.get_app_list()
-        print(app_list)
         self.assertIsInstance(app_list, list)
 
+    def test_describe_apps(self):
+        app_list = appbuilder.describe_apps()
+        self.assertIsInstance(app_list, list)
+        app_case = app_list[0]
+        self.assertIsInstance(app_case.id, str)
+        self.assertIsInstance(app_case.name, str)
+        self.assertIsInstance(app_case.description, str)
+        self.assertIn(app_case.appType, ["chatflow", "agent"])
+        self.assertIsInstance(app_case.isPublished, bool)
+        isSecondTimestamp = str(app_case.updateTime).isdigit() and len(str(app_case.updateTime)) < 13
+        self.assertTrue(isSecondTimestamp)
+
 if __name__ == '__main__':
     unittest.main()

docs/basic_module/appbuilder_client.md

@@ -636,7 +636,6 @@ class AppBuilderClientDemo {
 
         AppBuilderClientRunRequest request2 = new AppBuilderClientRunRequest(appId, conversationId);
         request2.setToolOutputs(ToolCallID, "北京今天35度");
-        request2.setToolOutputs(new AppBuilderClientRunRequest.ToolOutput[] {output});
         AppBuilderClientIterator itor2 = builder.run(request2);
         while (itor2.hasNext()) {
             AppBuilderClientResult result = itor2.next();

docs/basic_module/get_app_list.md

@@ -1,11 +1,11 @@
 # 获取AppBuilder已发布的应用列表
 
 ## 简介
-该接口可获取用户在 AppBuilder已发布的应用列表，包括模型名称、模型描述、模型的ID
+该接口可获取用户在 AppBuilder已发布的应用列表，包括应用名称、应用描述、应用的ID、应用类型、应用发布状态等
 
 ## Python基本用法
 
-### 获取app_list接口 `appbuilder.get_app_list()`
+### 获取app_list接口 `appbuilder.describe_apps()`
 
 #### 鉴权配置
 使用组件之前，请首先申请并设置鉴权参数，可参考[组件使用流程](https://cloud.baidu.com/doc/AppBuilder/s/Olq6grrt6#1%E3%80%81%E5%88%9B%E5%BB%BA%E5%AF%86%E9%92%A5)。
@@ -18,19 +18,24 @@ os.environ["APPBUILDER_TOKEN"] = "bce-YOURTOKEN"
 
 | 参数名称       | 参数类型   | 描述      | 示例值        |
 |------------|--------|---------|------------|
-| limit | int | 返回结果的最大数量，默认值为10, 最大值为100 | 10 |
-| after | str | 分页游标，返回结果中第一个应用的游标值，接口会返回该应用及之后的应用，用于分页查询。默认值为空字符串。 | app_id |
-| before | str | 返回结果中最后一个应用的游标值，与after原理一致，用于分页查询。默认值为空字符串。 | app_id |
+| maxKeys | int | 返回结果的最大数量，默认值为10, 最大值为100 | 10 |
+| marker | str | 分页游标，返回结果中第一个应用的游标值，接口会返回该应用及之后的应用，用于分页查询。默认值为空字符串。 | app_id |
 
 #### 返回参数
 
-`get_app_list`方法返回类型为 `list[AppOverview]`,其中 `AppOverview` 结构如下：
+`describe_apps`方法返回类型为 `list[AppOverview]`,其中 `AppOverview` 结构如下：
 
 ```python
 class AppOverview(BaseModel):
     id: str = Field("", description="应用ID")
     name: str = Field("", description="应用名称")
     description: str = Field("", description="应用简介")
+    appType: Optional[str] = Field(
+        None,
+        description="应用类型:agent、chatflow。agent:自主规划Agent, chatflow:工作流Agent。"
+    )
+    isPublished: Optional[bool] = Field(None, description="是否已发布")
+    updateTime: Optional[int] = Field(None, description="更新时间。时间戳，单位秒")
 ```
 
 
@@ -43,7 +48,7 @@ import appbuilder
 # 设置环境变量和初始化
 # 请前往千帆AppBuilder官网创建密钥，流程详见：https://cloud.baidu.com/doc/AppBuilder/s/Olq6grrt6#1%E3%80%81%E5%88%9B%E5%BB%BA%E5%AF%86%E9%92%A5
 os.environ["APPBUILDER_TOKEN"] = "..."
-app_list = appbuilder.get_app_list()
+app_list = appbuilder.describe_apps()
 print(app_list)
 ```
 
@@ -64,6 +69,12 @@ class AppOverview(BaseModel):
     id: str = Field("", description="应用ID")
     name: str = Field("", description="应用名称")
     description: str = Field("", description="应用简介")
+    appType: Optional[str] = Field(
+        None,
+        description="应用类型:agent、chatflow。agent:自主规划Agent, chatflow:工作流Agent。"
+    )
+    isPublished: Optional[bool] = Field(None, description="是否已发布")
+    updateTime: Optional[int] = Field(None, description="更新时间。时间戳，单位秒")
 ```
 
 #### 代码示例
@@ -85,36 +96,50 @@ print("创建的app总数为:{}".format(len(all_apps)))
 ## Java基本用法
 
 #### 接口参数及返回值
-与 `python appbuilder.get_app_list()`设计一致
+与 `python appbuilder.describe_apps()`设计一致
 
 #### 代码示例
 
 ```java
 public void GetAppsTest() throws IOException, AppBuilderServerException {
-    AppList builder = new AppList();
-    AppListRequest request = new AppListRequest();
-    request.setLimit(10);
-    assertNotNull(builder.getAppList(request)[0].getId());
+    AppList appList = new AppList();
+    AppsDescribeRequest request = new AppsDescribeRequest();
+    assertNotNull(appList.describeApps(request).getData()[0].getId());
 }
 ```
 
 ## Go基本用法
 
 #### 接口参数及返回值
-与 `python appbuilder.get_app_list()`设计一致
+与 `python appbuilder.describe_apps()`设计一致
 
 #### 代码示例
 
 ```go
-package appbuilder
-
-apps, err := GetAppList(GetAppListRequest{
-    Limit: 10,
-}, config)
-if err != nil {
-    t.Fatalf("get apps failed: %v", err)
+import (
+	"fmt"
+	"os"
+
+	"github.com/baidubce/app-builder/go/appbuilder"
+)
+
+func main() {
+  // 设置APPBUILDER_TOKEN、GATEWAY_URL环境变量
+	os.Setenv("APPBUILDER_TOKEN", "请设置正确的应用密钥")
+
+	config, err := appbuilder.NewSDKConfig("", "")
+	if err != nil {
+    fmt.Println("failed new sdk config: ", err)
+		return
+	}
+
+	maxKeys := 10
+	apps, err := appbuilder.DescribeApps(appbuilder.DescribeAppsRequest{MaxKeys: &maxKeys}, config)
+	if err != nil {
+    fmt.Println("get apps failed: ", err)
+	}
+	fmt.Println(len(apps.Data))
 }
-fmt.Println(len(apps))
 ```
 
 ## 高级用法
@@ -123,4 +148,5 @@ fmt.Println(len(apps))
 
 
 ## 更新记录和贡献
-* 千帆模型列表获取能力 (2024-7)
+* 千帆模型列表获取能力 (2024-7)
+* 接口结构升级(2024-11)

go/appbuilder/app_builder_client.go

@@ -30,6 +30,7 @@ import (
 	"time"
 )
 
+// Deprecated: 将废弃，请使用DescribeApps替代
 func GetAppList(req GetAppListRequest, config *SDKConfig) ([]App, error) {
 	request := http.Request{}
 	header := config.AuthHeaderV2()
@@ -86,6 +87,45 @@ func GetAppList(req GetAppListRequest, config *SDKConfig) ([]App, error) {
 	return rsp.Data, nil
 }
 
+func DescribeApps(req DescribeAppsRequest, config *SDKConfig) (DescribeAppsResponse, error) {
+	request := http.Request{}
+	header := config.AuthHeaderV2()
+	serviceURL, err := config.ServiceURLV2("/app?Action=DescribeApps")
+	if err != nil {
+		return DescribeAppsResponse{}, err
+	}
+	request.URL = serviceURL
+	request.Method = "POST"
+	header.Set("Content-Type", "application/json")
+	request.Header = header
+	data, _ := json.Marshal(req)
+	request.Body = NopCloser(bytes.NewReader(data))
+	config.BuildCurlCommand(&request)
+	client := config.HTTPClient
+	if client == nil {
+		client = &http.Client{Timeout: 300 * time.Second}
+	}
+	resp, err := client.Do(&request)
+	if err != nil {
+		return DescribeAppsResponse{}, err
+	}
+	defer resp.Body.Close()
+	requestID, err := checkHTTPResponse(resp)
+	if err != nil {
+		return DescribeAppsResponse{}, fmt.Errorf("requestID=%s, err=%v", requestID, err)
+	}
+	data, err = io.ReadAll(resp.Body)
+	if err != nil {
+		return DescribeAppsResponse{}, fmt.Errorf("requestID=%s, err=%v", requestID, err)
+	}
+	rsp := DescribeAppsResponse{}
+	if err := json.Unmarshal(data, &rsp); err != nil {
+		return DescribeAppsResponse{}, fmt.Errorf("requestID=%s, err=%v", requestID, err)
+	}
+
+	return rsp, nil
+}
+
 func NewAppBuilderClient(appID string, config *SDKConfig) (*AppBuilderClient, error) {
 	if appID == "" {
 		return nil, errors.New("appID is empty")

go/appbuilder/app_builder_client_data.go

@@ -216,10 +216,27 @@ type GetAppListResponse struct {
 	Message   string `json:"message"`
 }
 
+type DescribeAppsRequest struct {
+	Marker  *string `json:"marker,omitempty"`
+	MaxKeys *int    `json:"maxKeys,omitempty"`
+}
+
+type DescribeAppsResponse struct {
+	RequestID   string `json:"requestId"`
+	Marker      string `json:"marker"`
+	IsTruncated bool   `json:"isTruncated"`
+	NextMarker  string `json:"nextMarker"`
+	MaxKeys     int    `json:"maxKeys"`
+	Data        []App  `json:"data"`
+}
+
 type App struct {
 	ID          string `json:"id"`
 	Name        string `json:"name"`
 	Description string `json:"description"`
+	AppType     string `json:"appType,omitempty"`
+	IsPublished bool   `json:"isPublished,omitempty"`
+	UpdateTime  int64  `json:"updateTime,omitempty"`
 }
 
 type AppBuilderClientAnswer struct {