Common Foundation Tutorial

Feature Introduction

The Common Foundation module provides infrastructure-level capabilities of FlightHub 2 On-Premises version, divided by sub-tags:

System Health and Access: Service liveness probes for use by O&M platforms / load balancers / monitoring and alerting chains; business sides should not depend on them directly.

Access and Authorization / STS Credentials: Temporary credential applications for clients to "upload files directly to object storage", covering three scenarios: project-level general upload, business module customized upload, and flight record upload.

Security: Decryption capability for encrypted device SNs in flight records, allowing callers to restore encrypted SNs in task details to plaintext for device queries / display.

Object storage in the On-Premises version can be OSS / S3 / MinIO, etc., determined by the on-site deployment; the data.endpoint / data.bucket / data.object_key_prefix returned by the interface have been adapted to the deployment form. The caller can directly interface based on the returned values and must not hardcode any endpoint.

STS credentials have an expiration time (the data.credentials.expire field is the remaining valid seconds, not a unix timestamp). The client should renew or reapply before expiration; continued use after expiration will be rejected by the object storage SDK.

The data.object_key_prefix returned in the credentials is a mandatory constraint: the server isolates project data by this prefix, and credentials can only read/write files under this prefix; exceeding the prefix will be rejected by object storage signing.

For the complete fields of the STS response (including provider / region / bucket / endpoint / object_key_prefix and nested credentials.{access_key_id, access_key_secret, security_token, expire}), see Response Result → Successful Return Example.

Interface Usage Flow

System Health Check

The probe interface exposed externally by the DRC service. The service is considered ready when the response is HTTP 200 and code = 0.

Call steps:

Call DRC Service Health Check (GET /openapi/v2.0/drc/health), no business parameters required (and no x-user-token required).

Use HTTP status code + body code for joint judgment: HTTP=200 and code=0 indicates DRC service is available; other cases are considered unavailable, triggering monitoring alerts or traffic removal.

Project-level Direct File Upload (General STS)

The most commonly used "client direct upload → object storage" flow, regardless of business module:

Call steps:

Call Get Project-level Direct File Upload STS Credentials (POST /openapi/v2.0/storage/api/v1/workspaces/{workspace_id}/sts); the path parameter workspace_id is the target project UUID (see Public Parameters → Path Parameters).

Obtain the fields in the nested structure in the response: data.{provider, region, bucket, endpoint, object_key_prefix} and data.credentials.{access_key_id, access_key_secret, security_token, expire}.

On the client, use the object storage SDK (OSS / S3 / MinIO) to initiate PUT with temporary credentials; the object key must start with the data.object_key_prefix returned by the server, otherwise it will be rejected.

When the credentials are about to expire (data.credentials.expire is the remaining valid seconds), call this interface again to renew.

Business Module Customized STS

Applicable to some business modules with dedicated OSS path planning (such as media download, model upload, change detection reports, etc.):

Call steps:

Call Get Business Module Customized STS Credentials (POST /openapi/v2.0/storage/api/v1/projects/{proj_uuid}/custom-sts), body fields:

usage (required, string): The business module to which it belongs. The spec currently only declares the enum value alert-pdf-share; other values require backend authorization first.

temp (optional, bool): Whether it is temporary data (temporary data has a shorter cleanup cycle).

path (optional, string): Optional sub-path.

The server concatenates the limited data.object_key_prefix by usage + temp + path and issues temporary credentials that can only read/write under that prefix. The response field structure is consistent with Project-level Direct File Upload STS (nested data.credentials).

The client uses the credentials according to the object key rules agreed by the business module.

General business integration does not need to call this interface directly; it is usually encapsulated within the "upload / import" flow of each business module; only custom extension businesses need to call it actively.

When the usage value is not authorized (not in the allowed set configured by the backend), the backend file-storage will reject it with HTTP 200 + business code = 217009 (message: "invalid path"); not 200400.

Flight Record Upload

After each flight, the dock or Pilot will upload raw data such as flight control records and black box logs to the cloud, using a dedicated STS:

Call steps:

Call Get Flight Record Upload STS Credentials (GET /openapi/v2.0/manage/api/v1/workspaces/{uuid}/flight-tasks/sts-info).

After obtaining the STS credentials limited to the "this project-this flight" directory prefix, directly PUT files according to the object storage protocol.

After the file upload is complete, the archival status is confirmed by the callback or active query interface of the "Flight Tasks" module (see Flight Tasks Tutorial for details).

Device SNs in flight task records are stored in encrypted form (Base64 strings). When the caller obtains flight task details and needs to use these encrypted SNs for device queries or display, call this interface for batch restoration.

Call steps:

Obtain task details via the Flight Tasks module and identify encrypted SN fields.

Call Decrypt Device Serial Numbers (SN) in Flight Records (POST /openapi/v2.0/manage/api/v1/workspaces/{workspace_id}/flight-tasks/decrypt-sn), request body { "encrypted_sns": ["<base64-1>", "<base64-2>", ...] }, encrypted_sns is required.

After receiving the plaintext SNs, use them for device queries, device topology display, and other flows.

This interface only performs two-way mapping: input encrypted SN list, return the corresponding plaintext SN list, without business verification.

In On-Premises deployments, the encryption key is maintained by the deployment party; the plaintext SNs received by the caller are consistent with the SNs queryable via "Device Management" interfaces and can be directly used as device_sn / sn parameters.

Common Issues Interacting with Object Storage

The following are common rejection reasons on the object storage side (OSS / S3 / MinIO protocol layer), unrelated to FlightHub OpenAPI business error codes:

Symptom	Possible Cause	Recommended Handling
Upload 403 / `AccessDenied`	Object key does not start with `data.object_key_prefix` / credentials expired / operation not in STS authorization list (such as unauthorized DELETE)	Check key concatenation, `expire` remaining seconds, whether the operation permission has been granted by STS
Upload 403 / `InvalidAccessKeyId`	Client cached old credentials / credentials expired	Clear cache and reapply for STS
Slow upload / failure	Object storage endpoint unreachable	In On-Premises deployment, the endpoint may be on the intranet; confirm that the caller's network is reachable; if necessary, contact the deployment party for NAT / domain resolution

Feature Introduction#

Interface Usage Flow#

System Health Check#

Project-level Direct File Upload (General STS)#

Business Module Customized STS#

Flight Record Upload#

Decrypt Device SNs in Flight Records#

Common Issues Interacting with Object Storage#

Feature Introduction

Interface Usage Flow

System Health Check

Project-level Direct File Upload (General STS)

Business Module Customized STS

Flight Record Upload

Decrypt Device SNs in Flight Records

Common Issues Interacting with Object Storage