快速入门

本文档以创建重建算法作业为例进行说明，在阅读过程中可通过 API 文档查询相关接口的调用。

获取 AK/SK

登录开发者网站open in new window后进入大疆智图 API 控制台open in new window，点击 [申请开通] 按钮，等待后台审核通过后，大疆智图 API 控制台将展示您的 AK/SK （App Key, Secret Key）信息，下图为 AK/SK 信息展示示例。

图. 大疆智图 API AK/SK 信息

获取 Token

开发者从本地设备向服务器发送请求时，需要在大疆智图 API 中使用 AK/SK 认证，借助 HMAC 签名算法open in new window为开发者的请求消息添加签名。

以下为获取 Token 实例，请自行替换您的 AK/SK。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/store/obtain_token
HTTP_METHOD=POST
payload=$(
	cat <<EOF
EOF
)


function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")
curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

返回结果说明：

accessKeyID、secretAccessKey、sessionToken、region、cloudBucketName、storePath、callbackParam等字段在 SDK 例子会使用到。
如果 token 过期，请重新获取新 token，再继续上传。

准备素材

对于 2D、3D、LiDAR 重建作业，开发者可以通过以下的方式准备素材：

使用自己准备的素材，并存储到本地。
使用官网提供的样例素材，下载并解压到本地。路径结构示例：D:\data\二维-2D 和D:\data\三维-3D。因为这两个压缩包不仅包含原始的素材，也包含重建的结果文件，所以在这个流程中，我们只要上传原始素材即可，即把素材上传代码实例中的 local_folder 变量赋值为 D:\data\二维-2D\5cm-正射影像-2D-53pic 或 D:\data\三维-3D\3cm-三维影像-3D-70pic。

安装存储服务的 SDK

请先安装阿里云 OSS SDK，用于上传素材到 DJI Terra 在阿里云 OSS 的桶内。详细说明参见官方文档open in new window。

Python SDK 安装命令： pip install oss2

使用阿里云 OSS SDK 上传素材

需要自行配置 “阿里云 OSS 访问信息” 与 “本地文件夹路径”，前者为获取 Token 步骤的返回信息，后者为需要上传的素材的访问地址。脚本执行的结果打印出现 “uploaded” 字样，即为上传成功。local_folder 变量赋值示例：D:\data\二维-2D\5cm-正射影像-2D-53pic 或 D:\data\三维-3D\3cm-三维影像-3D-70pic

注意： uploaded_files.json 文件，会在关联文件的接口里使用

上传素材实例：

import os
import oss2

endpoint = 'http://oss-cn-hangzhou.aliyuncs.com'

# 配置阿里云 OSS 访问信息
access_key_id = '{your access id}'
access_key_secret = '{your access key}'
bucket_name = '{your bucket name}'
token = '{your token}'
store_path = '{your store path}'

store_root_path = store_path[:store_path.rfind('/{fileName}')]

# 创建 STS 访问凭证
sts_auth = oss2.StsAuth(access_key_id, access_key_secret, token)

# 创建 OSS 客户端
bucket = oss2.Bucket(sts_auth, endpoint, bucket_name)
bucket.timeout = 600

# 本地文件夹路径
local_folder = r'本地素材的待上传的路径'

# 遍历本地文件夹
uploaded_files = []
for root, dirs, files in os.walk(local_folder):
    for file_name in files:
        local_file_path = os.path.join(root, file_name)
        relative_path = os.path.relpath(os.path.join(root, file_name), local_folder)
        oss_file_path = os.path.join(store_root_path, relative_path)
        oss_file_path = oss_file_path.replace("\\", "/")
        put_result = bucket.put_object_from_file(oss_file_path, local_file_path)
        etag = put_result.etag
        # 保存结果的 etag，需要在 `关联文件` 步骤里用到
        print(f"Uploaded: {local_file_path} -> {oss_file_path}, etag: {etag}")
        container_file_path = relative_path.replace("\\", "/")
        uploaded_files.append({"name": container_file_path, "etag": etag, "checksum": etag})

if uploaded_files:
    import json
    with open("./uploaded_files.json", "w") as f:
        json.dump(uploaded_files, f)

创建 resource

DJI_APP_KEY 和 DJI_SECRET_KEY 请自行替换为您的 AK/SK。返回值中的 resource uuid 将在后续使用。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/resources
HTTP_METHOD=POST

payload=$(
	cat <<EOF
{"name": "test_resource", "type": "map"}
EOF
)

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

关联文件

dji_app_key 和 dji_secret_key 请自行替换为您的 AK/SK。 resource_uuid 替换为创建 resources 步骤的返回值。callbackParam 替换为获取 Token 步骤的返回值。

关联文件 python 实例：

import base64
import hashlib
import hmac
import json
import time

import requests

dji_app_key = "{your app key}"
dji_secret_key = b"{your secret key}"
uri = "/terra-rescon-be/v2/store/upload_callback"
resource_uuid = "{your created resource uuid}"
callback_param = "{callbackParam from token}"

host = "https://openapi-cn.dji.com"
url = host + uri
method = "POST"


def bind_batch_files(files):
    payload = {
        "resourceUUID": resource_uuid,
        "callbackParam": callback_param,
        "files": files,
    }

    digest = (
        lambda x: base64.b64encode(hashlib.sha256(x.encode("utf-8")).digest()).decode(
            "utf-8"
        )
    )(json.dumps(payload))

    gmt_time = time.strftime("%a, %d %b %Y %H:%M:%S GMT", time.gmtime(time.time()))
    signing_string = f"date: {gmt_time}\n@request-target: {method.lower()} {uri}\ndigest: SHA-256={digest}"
    signature = (
        lambda secret, x: base64.b64encode(
            hmac.new(secret, x.encode("utf-8"), hashlib.sha256).digest()
        ).decode("utf-8")
    )(dji_secret_key, signing_string)

    headers = {
        "Content-Type": "application/json",
        "Date": gmt_time,
        "Digest": f"SHA-256={digest}",
        "Authorization": f'hmac username="{dji_app_key}", algorithm="hmac-sha256", headers="date @request-target digest", signature="{signature}"',
    }

    r = requests.post(url, json=payload, headers=headers)
    print(r.request.headers)
    print(r.content)
    print(r.headers)


if __name__ == "__main__":
    with open("./uploaded_files.json", "r") as f:
        uploaded_files = json.load(f)

    mini_batch = []
    for item in uploaded_files:
        mini_batch.append(item)
        if len(mini_batch) >= 50:
            bind_batch_files(mini_batch)
            mini_batch = []

    if mini_batch:
        bind_batch_files(mini_batch)

创建 job

请自行替换您的 AK/SK，返回值中的 job uuid 将在将在后续使用。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/jobs
HTTP_METHOD=POST

payload=$(
	cat <<EOF
{"name": "test_name"}
EOF
)


function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

启动 job

启动 2D 类型 job

请自行替换您的 AK/SK。脚本需要替换 job uuid 与 resource uuid。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/jobs/{your uuid}/start
HTTP_METHOD=POST

payload=$(
	cat <<EOF
{"type": 14, "resourceUuid": "{uuid from create resource}", "parameters": "{\"parameter\":{\"map_mode\":1,\"quality_level\":1,\"output_geo_desc\":{\"cs_type\":\"GEO_CS\",\"geo_cs\":\"EPSG:32650\",\"geo_cs_wkt\":\"\",\"override_vertical_cs\":\"\"}}}"}
EOF
)

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

启动 3D 类型 job

请自行替换您的 AK/SK。脚本需要替换 job uuid 与 resource uuid。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/jobs/{uuid from create job}/start
HTTP_METHOD=POST

payload=$(
    cat <<EOF
{"type": 15, "resourceUUID": "{uuid from create resource}", "parameters": "{\"parameter\":{\"output_mesh\":true,\"generate_obj\":true,\"generate_b3dm\":true,\"generate_osgb\":true}}"}
EOF
)

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

启动 LiDAR 类型 job

请自行替换您的 AK/SK。脚本需要替换 job uuid 和 resource uuid 参数。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/jobs/{uuid from create job}/start
HTTP_METHOD=POST

payload=$(
	cat <<EOF
	{"type": 13, "resourceUuid": "{uuid from create resource}",  "parameters": "{\"parameter\":{\"sample_distance\":0.2,\"output_pointcloud\":true,\"generate_pnts\":true,\"generate_las\":true,\"output_geo_desc\":{\"cs_type\":\"GEO_CS\",\"geo_cs\":\"EPSG:32649\",\"geo_cs_wkt\":\"\",\"override_vertical_cs\":\"\"}}}"}
EOF
)

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8' \
	-d "$payload" -v

查询 job 状态

作业发起后可以定时轮询 job 状态

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/jobs/{uuid from create job}
HTTP_METHOD=GET

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8'

下载计算结果

当作业成功完成时，下载计算结果的步骤为：

首先通过查询 job 状态获取返回的 outputResourceUuid
查询 resource 获取文件 uuid (也可以通过查询文件接口，传入 resource uuid 作为条件获取文件分页信息)
通过文件的 uuid 下载。

下面通过查询 resource 的方式来进行下载：

获取文件 uuid 列表

请替换为查询 job 状态返回的 outputResourceUuid。

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/resources/{uuid form check job status}
HTTP_METHOD=GET

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8'

获取文件信息

上一步执行完成后将返回 uuid 列表

#!/bin/bash

DJI_APP_KEY="{your AK}"
DJI_SECRET_KEY="{your SK}"
URI=/terra-rescon-be/v2/files/{file uuid}
HTTP_METHOD=GET

function calculate_signature() {
	content="$1"
	signature=$(echo -n -e "${content}" | openssl dgst -sha256 -hmac "${DJI_SECRET_KEY}" -binary | openssl enc -base64 -A)
	echo ${signature}
}

HOST=https://openapi-cn.dji.com

url=${HOST}${URI}
x_date=$(date -u +"%a, %d %b %Y %H:%M:%S GMT")
lower_method=$(echo "${HTTP_METHOD}" | tr '[:upper:]' '[:lower:]')
digest=$(echo -n "${payload}" | openssl dgst -sha256 -binary | base64)
request_signature=$(calculate_signature "date: ${x_date}\n@request-target: ${lower_method} ${URI}\ndigest: SHA-256=${digest}")

curl -X ${HTTP_METHOD} ${url} \
	-H "Date: ${x_date}" \
	-H "Digest: SHA-256=${digest}" \
	-H "Authorization: hmac username=\"${DJI_APP_KEY}\", algorithm=\"hmac-sha256\", headers=\"date @request-target digest\", signature=\"${request_signature}\"" \
	-H 'Content-Type: application/json;charset=UTF-8'

下载所有文件

遍历第二步中的所有文件 uuid，并通过调用接口 /terra-rescon-be/v2/files 或者 /terra-rescon-be/v2/files/:uuid。传入文件 uuid 以获取对应的文件 URL（注意：如果将该 URL 打印到屏幕上，会经过 unicode-escape 编码，因此需要解码后才能直接点击下载，详细请参阅FAQ）。最后使用文件 URL 进行文件下载。

结果文件导入Terra软件

重建参数中的成果导出参数，设置 ’pc_dir_structure‘ 参数为 true（ps：详情见算法参数介绍 页面）。重建结果输出目录与本地的 Terra 软件的重建结果输出目录是保持一致，各类型任务的重建结果根目录结构如下：

# 二维成果目录结构
    成果根目录/
    ├── AT
    ├── map
    ├── images
    ├── mission.json
# 三维成果目录结构
    成果根目录/
    ├── AT
    ├── models
    ├── images
    ├── mission.json
# Lidar成果目录结构
    成果根目录/
    ├── AT
    ├── lidars
    ├── mission.json

将成果文件按以上目录结构打包为 zip 包，即可导入到 Terra 软件中进行查看。如果下载文件的目录结构与上述不一致，则需要进行调整，使其与上述目录结构保持一致，才能正常导入到 Terra 软件中进行查看。

快速入门

# 获取 AK/SK

# 获取 Token

# 准备素材

# 安装存储服务的 SDK

# 使用阿里云 OSS SDK 上传素材

# 创建 resource

# 关联文件

# 创建 job

# 启动 job

# 启动 2D 类型 job

# 启动 3D 类型 job

# 启动 LiDAR 类型 job

# 查询 job 状态

# 下载计算结果

# 获取文件 uuid 列表

# 获取文件信息

# 结果文件导入Terra软件