vitepress-template

Appearance

API Endpoints and Service Interfaces ​

**Referenced Files in This Document** - [[README.md]](file/bi-analysis/readme.md) - [[common.proto]](file/bi-analysis/api/anls/v1/common.proto) - [[home.proto]](file/bi-analysis/api/anls/v1/home.proto) - [[field.proto]](file/bi-analysis/api/anls/v1/field.proto) - [[query.proto]](file/bi-analysis/api/anls/v1/query.proto) - [[table.proto]](file/bi-analysis/api/anls/v1/table.proto) - [[template.proto]](file/bi-analysis/api/anls/v1/template.proto) - [[common.proto]](file/bi-analysis/api/anls-m/v1/common.proto) - [[dimension.proto]](file/bi-analysis/api/anls-m/v1/dimension.proto) - [[field.proto]](file/bi-analysis/api/anls-m/v1/field.proto) - [[field_group.proto]](file/bi-analysis/api/anls-m/v1/field-group.proto) - [[field_meta.proto]](file/bi-analysis/api/anls-m/v1/field-meta.proto)

Table of Contents ​

  1. Introduction
  2. Project Structure
  3. Core Components
  4. Architecture Overview
  5. Detailed Component Analysis
  6. Dependency Analysis
  7. Performance Considerations
  8. Troubleshooting Guide
  9. Conclusion

Introduction ​

This document provides comprehensive API documentation for the bi-analysis service, covering both REST HTTP endpoints and gRPC service definitions. It describes HTTP methods, URL patterns, request/response schemas, parameter specifications, authentication/authorization, and operational guidance. The service exposes two primary API families:

  • Client-facing APIs under anls/v1 for end-user dashboards and ad-hoc queries
  • Management APIs under anls-m/v1 for administrators to manage dimensions, metrics, metric groups, and metadata

The unified response format and OpenAPI generation pipeline are documented to aid integration and maintenance.

Project Structure ​

The bi-analysis service organizes its API definitions by module and version, with each module containing:

  • A common.proto for global Swagger/OpenAPI configuration and shared enums
  • One or more entity-specific .proto files defining gRPC services and messages
  • HTTP annotations mapping gRPC methods to REST endpoints

Diagram sources

Section sources

Core Components ​

  • Unified response format: All HTTP responses follow a consistent envelope with code, message, and data fields. Pagination responses include total and list.
  • OpenAPI/Swagger: Global swagger info and tag definitions are configured via common.proto, enabling automated documentation generation and synchronization.
  • Validation: Protobuf validation rules are applied to enforce parameter constraints on requests.

Key references:

  • Unified response format and pagination structure
  • Swagger global configuration and tag hierarchy
  • Validation annotations in request messages

Section sources

Architecture Overview ​

The bi-analysis service exposes gRPC services that are automatically translated to REST endpoints via HTTP annotations. Clients can integrate using either gRPC or REST. The management APIs (anls-m/v1) are intended for administrative operations, while client APIs (anls/v1) serve dashboard and query needs.

[No sources needed since this diagram shows conceptual workflow, not actual code structure]

Detailed Component Analysis ​

Client API Family (anls/v1) ​

HomeService ​

  • Purpose: Save and retrieve user homepage layout configurations.
  • Endpoints:
    • POST /api/v1/anls/home/set
    • POST /api/v1/anls/home/get
  • Request/Response:
    • SetHomeLayoutRequest: type (string), widgetLayoutData (ListValue)
    • SetHomeLayoutReply: empty
    • GetHomeLayoutRequest: type (string)
    • GetHomeLayoutReply: widgetLayoutData (ListValue)
  • Notes: widgetLayoutData uses dynamic JSON structure compatible with ListValue.

Section sources

FieldService ​

  • Purpose: Manage custom, order, formula, and period field configurations.
  • Endpoints:
    • POST /api/v1/anls/fields
    • POST /api/v1/anls/fields/delete
    • POST /api/v1/anls/fields/order
    • POST /api/v1/anls/fields/formula
    • POST /api/v1/anls/fields/period
    • POST /api/v1/anls/fields/order/delete
    • POST /api/v1/anls/fields/formula/delete
    • POST /api/v1/anls/fields/period/delete
  • Request/Response:
    • SaveFieldRequest: id (int64), i_diy_table_id (int64), c_display (string), c_unit (string), c_display_tips (string), c_display_image (string)
    • SaveFieldReply: id (int64)
    • DeleteFieldRequest: id (int64)
    • SaveOrderFieldRequest: id (int64), c_display (string), c_date_type (string), c_table_field (string), c_display_tips (string), c_display_image (string), c_where (repeated WhereCondition)
    • WhereCondition: field (string), operator (string), value (string)
    • SaveFormulaFieldRequest: id (int64), c_display (string), c_unit (string), c_display_tips (string), c_expression (string)
    • SavePeriodFieldRequest: id (int64), c_field (string), c_display (string), c_date_type (string), c_func (string), i_start_diff_day (int32), i_end_diff_day (int32), t_start_date (string), t_end_date (string), c_display_tips (string)
    • Delete* requests accept id (int64) and return empty replies.

Section sources

QueryService ​

  • Purpose: Execute preview queries and return SQL for debugging.
  • Endpoints:
    • POST /api/v1/anls/query/preview
    • POST /api/v1/anls/query/sql
  • Request/Response:
    • PreviewRequest: c_row (string), c_col (string), c_field (string), c_field_config (string), c_style (string), search (SearchCondition), page (int32), limit (int32), c_order_by (string), c_order (string), b_rank (int32), b_sum (int32)
    • SearchCondition: t_date (repeated string), i_shop_id (repeated int64), c_product_id (repeated string), i_head_oper (repeated int64), i_helper_oper (repeated int64), i_manager_oper (repeated int64), i_category_id (repeated int64), c_cid (repeated string), c_biz_status (repeated string), c_outer_id (repeated string), c_platform (string), cache (int32), c_title (string), c_status (string), i_collect_id (repeated int64)
    • PreviewReply: config (QueryConfig), list (repeated Struct), count (string), sql (string)
    • QueryConfig: row (repeated string), col (repeated string), field (repeated string)
    • GetSQLReply: sql (string)

Filtering and pagination:

  • Pagination: page and limit fields control paging.
  • Sorting: c_order_by and c_order specify sort column and direction.
  • Ranking and totals: b_rank and b_sum toggle ranking and aggregated-only mode.

Section sources

TableService ​

  • Purpose: Manage custom data tables and related CRUD operations.
  • Endpoints:
    • GET /api/v1/anls/tables
    • POST /api/v1/anls/tables
    • POST /api/v1/anls/tables/data/batch
    • POST /api/v1/anls/tables/data/list
    • POST /api/v1/anls/tables/data
  • Request/Response:
    • ListTableRequest: empty
    • ListTableReply: list (repeated TableInfo)
    • CreateTableRequest: c_display (string), c_dimension (string), c_description (string), i_sort (int32)
    • CreateTableReply: id (int64)
    • BatchSetDiyValueRequest: i_diy_table_id (int64), data (repeated Struct)
    • DiyTableDetailRequest: id (int64), page (int32), limit (int32), search (Struct)
    • DiyTableDetailReply: list (repeated Struct), count (int64)
    • SetDiyValueRequest: i_diy_table_id (int64), dimension (map<string,string>), value (map<string,double>)
    • SetDiyValueReply: fields (map<string,string>), b_ins (string)

Notes:

  • Dimensions and values are passed as dynamic fields; batch operations support up to 1000 rows per request.

Section sources

TemplateService ​

  • Purpose: Manage saved analysis templates.
  • Endpoints:
    • POST /api/v1/anls/template/set
    • POST /api/v1/anls/template/info
    • POST /api/v1/anls/template/list
    • POST /api/v1/anls/template/delete
    • POST /api/v1/anls/template/sort
  • Request/Response:
    • SetTemplateRequest: id (int64), c_name (string), c_icon (string), c_color (string), c_row (string), c_col (string), c_field (string), c_field_config (string), c_remark (string), i_sort (int32)
    • SetTemplateReply: id (string)
    • GetTemplateInfoRequest: id (int64)
    • GetTemplateInfoReply: fields similar to TemplateInfo (no nested data)
    • ListTemplatesRequest: empty
    • ListTemplatesReply: list (repeated TemplateInfo)
    • DeleteTemplateRequest: id (int64)
    • SetTemplateSortRequest: data (repeated TemplateSortItem)
    • TemplateSortItem: id (int64), i_sort (int32)
    • SetTemplateSortReply: empty

Section sources

Management API Family (anls-m/v1) ​

DimensionService ​

  • Purpose: Manage dimensions used for grouping and filtering.
  • Endpoints:
    • GET /api/v1/anls-m/dimensions
    • POST /api/v1/anls-m/dimensions
    • PUT /api/v1/anls-m/dimensions/
    • PUT /api/v1/anls-m/dimensions/{id}/status
    • DELETE /api/v1/anls-m/dimensions/
    • POST /api/v1/anls-m/dimensions/batch-delete
  • Request/Response:
    • ListDimensionRequest: c_key (string), c_name (string), status (optional int32)
    • ListDimensionReply: list (repeated DimensionInfo)
    • CreateDimensionRequest: c_key (string), c_name (string), c_mutex_keys (string), i_sort (int32), remark (string)
    • UpdateDimensionRequest: id (int64), c_key (string), c_name (string), c_mutex_keys (string), i_sort (int32), remark (string)
    • UpdateDimensionStatusRequest: id (int64), status (int32 in {0,1})
    • DeleteDimensionRequest: id (int64)
    • BatchDeleteDimensionRequest: ids (repeated string, min 1)

Section sources

FieldMService ​

  • Purpose: Manage metric definitions for reporting.
  • Endpoints:
    • GET /api/v1/anls-m/fields
    • POST /api/v1/anls-m/fields
    • PUT /api/v1/anls-m/fields/
    • DELETE /api/v1/anls-m/fields/
    • PUT /api/v1/anls-m/fields/{id}/status
    • GET /api/v1/anls-m/fields/options
  • Request/Response:
    • ListFieldMRequest: pagination (PageRequest), c_display (string), c_group (string), status (optional), is_template (optional), c_table_name (string)
    • ListFieldMReply: total (int64), list (repeated FieldMInfo)
    • CreateFieldMRequest: c_field (string), c_display (string), c_group (string), c_table_name (string), c_table_field (string), c_type (string), c_location (string), c_display_tips (string), c_display_image (string), c_unit (string), c_expression (string), c_func (string), c_dimension (string), c_date_type (string), c_where (string), is_template (int32), i_sort (int32)
    • UpdateFieldMRequest: id (int64), and selected fields to update
    • UpdateFieldStatusMRequest: id (int64), status (int32 in {0,1})
    • ListFieldOptionsRequest: c_group (string), is_template (optional)
    • ListFieldOptionsReply: list (repeated FieldOption)

Section sources

FieldGroupService ​

  • Purpose: Manage metric group definitions.
  • Endpoints:
    • GET /api/v1/anls-m/field-groups
    • POST /api/v1/anls-m/field-groups
    • PUT /api/v1/anls-m/field-groups/
    • DELETE /api/v1/anls-m/field-groups/
    • PUT /api/v1/anls-m/field-groups/{id}/status
    • GET /api/v1/anls-m/field-groups/options
  • Request/Response:
    • ListFieldGroupRequest: pagination (PageRequest), c_name (string), status (optional), allow_template (optional)
    • ListFieldGroupReply: total (int64), list (repeated FieldGroupInfo)
    • CreateFieldGroupRequest: c_key (string), c_name (string), allow_template (int32 in {0,1}), i_sort (int32)
    • UpdateFieldGroupRequest: id (int64), c_name (string), allow_template (optional), i_sort (optional)
    • UpdateFieldGroupStatusRequest: id (int64), status (int32 in {0,1})
    • ListFieldGroupOptionsRequest: allow_template (optional)
    • ListFieldGroupOptionsReply: list (repeated FieldGroupOption)

Section sources

FieldMetaService ​

  • Purpose: Manage metadata for underlying table fields (data types, operators, filters).
  • Endpoints:
    • GET /api/v1/anls-m/field-metas
    • GET /api/v1/anls-m/field-metas/
    • POST /api/v1/anls-m/field-metas
    • PUT /api/v1/anls-m/field-metas/
    • DELETE /api/v1/anls-m/field-metas/
    • PUT /api/v1/anls-m/field-metas/{id}/status
    • GET /api/v1/anls-m/field-meta-options
  • Request/Response:
    • ListFieldMetaRequest: pagination (PageRequest), c_display (string), c_group (string), status (optional), is_metric (optional), is_filter (optional)
    • ListFieldMetaReply: total (int64), list (repeated FieldMetaInfo)
    • GetFieldMetaRequest: id (int64)
    • GetFieldMetaReply: data (FieldMetaInfo)
    • CreateFieldMetaRequest: c_table_field (string), c_display (string), c_group (string), c_data_type (string), c_date_type (string), is_metric (int32 in {0,1}), c_func (string), c_related_filters (string), is_filter (int32 in {0,1}), c_operators (string), c_enum_values (string), remark (string), i_sort (int32)
    • UpdateFieldMetaRequest: id (int64), and selected fields to update
    • UpdateFieldMetaStatusRequest: id (int64), status (int32 in {0,1})
    • ListFieldMetaOptionsRequest: c_group (string), is_metric (optional), is_filter (optional)
    • ListFieldMetaOptionsReply: list (repeated FieldMetaOption)

Section sources

Authentication, Authorization, and Security ​

  • Authentication: Not specified in the provided proto files. Consult your gateway or middleware configuration for JWT/OAuth handling.
  • Authorization: Not specified in the provided proto files. Ensure RBAC policies are enforced at the gateway or service boundary.
  • Security considerations:
    • Validate and sanitize all inputs, especially dynamic JSON fields (ListValue, Struct).
    • Enforce parameter limits (e.g., batch sizes) to prevent resource exhaustion.
    • Apply rate limiting at the gateway level.
    • Use HTTPS/TLS for production traffic.

[No sources needed since this section provides general guidance]

Query Parameters, Filtering, Pagination, and Sorting ​

  • Query parameters:
    • Client API (QueryService): c_row, c_col, c_field, c_field_config, c_style, page, limit, c_order_by, c_order, b_rank, b_sum, search.* fields
    • Management API (List* requests): pagination (PageRequest), plus filter fields like c_display, c_group, status, is_template, c_table_name, c_key, c_name, allow_template, c_table_field, c_data_type, is_metric, is_filter
  • Filtering:
    • SearchCondition supports date ranges, ID lists, platform, title/status, and collection filters.
    • Additional filters include category IDs, platform categories, business statuses, outer IDs.
  • Pagination:
    • page and limit control paging; defaults are defined in request messages.
  • Sorting:
    • c_order_by and c_order define sort column and direction.

Section sources

Examples and Error Responses ​

  • Example usage patterns:
    • Save a custom field: POST /api/v1/anls/fields with SaveFieldRequest payload.
    • Preview a pivot query: POST /api/v1/anls/query/preview with PreviewRequest payload.
    • Create a dimension: POST /api/v1/anls-m/dimensions with CreateDimensionRequest payload.
  • Error responses:
    • Follow the unified response envelope. Use the code/message fields to determine failure reasons.
    • Validation errors will occur when request fields violate protobuf validation rules.

Section sources

Dependency Analysis ​

The HTTP endpoints are generated from gRPC service definitions via annotations. The management APIs share common PageRequest definitions from bi-common.

Diagram sources

Section sources

Performance Considerations ​

  • Prefer paginated queries with appropriate limit values to avoid large payloads.
  • Use c_order_by and c_order to leverage database indexes where applicable.
  • Avoid excessive dynamic JSON nesting; keep c_field_config concise.
  • For batch operations (e.g., batch set diy values), adhere to the maximum item limits defined in validation rules.
  • Enable caching selectively via cache flags where supported.

[No sources needed since this section provides general guidance]

Troubleshooting Guide ​

  • Validation failures: Ensure request fields meet validation constraints (length, allowed values, numeric ranges).
  • Missing authentication/authorization: Verify gateway middleware configuration and tokens.
  • Unexpected empty results: Confirm filter values and date ranges; check pagination parameters.
  • Large response sizes: Reduce limit or refine filters.

Section sources

Conclusion ​

The bi-analysis service provides a comprehensive set of REST and gRPC endpoints for managing dashboard layouts, custom fields, queries, templates, and administrative resources. By adhering to the unified response format, validation rules, and pagination/filtering patterns described here, clients can integrate reliably and efficiently. For production deployments, ensure proper authentication/authorization, rate limiting, and TLS termination at the gateway.