Справочник по API

Все API на этой странице используют метод POST и тело запроса в формате JSON. В каждом запросе передаются Общие заголовки запроса; для отдельных API они не повторяются. Внешняя структура ответа описана в разделе Единая структура ответа; в разделе «Ответ» каждого API перечислены только бизнес-поля внутри data.

Домены

Общие заголовки запроса

Каждый API требует следующих параметров заголовка.

Единая структура ответа

Все API возвращают одинаковую внешнюю структуру. Внешний code отражает только результат на уровне API; бизнес-результат смотрите в data.bizCode.

Примечание: вызов считается успешным, только если одновременно code == 0 и data.bizCode == 0.

Создание задачи и получение учётных данных для загрузки

Создаёт задачу моделирования и выдаёт временные учётные данные облачного хранилища для загрузки входных данных.

Endpoint

POST /open-apis/spatial-model/v1/model/create

Ограничения

Параметры запроса

Ответ

Пример запроса

POST /open-apis/spatial-model/v1/model/create HTTP/1.1
Host: open-api-gw.xgrids.com
APP-ID: your_app_id
X-Timestamp: 1791763200
X-Nonce: a3f91c2d8e7b4a6590fd12cb77ae40d1
X-Sign: 9mQk7xL2vTbR4pNw8sYcA1dHfZ3eJgU6oIyK0rVnBsM=
Content-Type: application/json

{
  "modelName": "Design Commune C Facade",
  "modelDes": "Nanshan, Shenzhen, LCC2 scene package",
  "quality": "2",
  "autoRebuild": 1,
  "tags": ["facade", "nanshan"]
}

Пример ответа

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizCode": 0,
    "bizMsg": "",
    "modelId": 100231987,
    "params": {
      "cloudService": "AWS",
      "endpoint": "s3.ap-southeast-1.amazonaws.com",
      "region": "ap-southeast-1",
      "bucket": "your-bucket-name",
      "savePath": "prd/spatial-model/{accountId}/{taskCode}/input/",
      "accessKeyId": "ASIA****************",
      "accessKeySecret": "wJalrXUtnFEMI/K7MDENG/bPxRfiCY****",
      "securityToken": "IQoJb3JpZ2luX2VjE****",
      "requestId": "b7f1e2a9-5c43-4d8e-9a10-6f2c3b84d517"
    }
  }
}

Запуск задачи

Запускает моделирование вручную.

Endpoint

POST /open-apis/spatial-model/v1/model/start

Ограничения

Параметры запроса

Ответ

Возвращается только Единая структура ответа.

Пример запроса

{
  "modelId": 100231987
}

Повторное получение учётных данных для загрузки

Выдаёт новые временные учётные данные для загрузки, если загрузка прервалась или срок действия временных учётных данных истёк.

Endpoint

POST /open-apis/spatial-model/v1/model/sts

Ограничения

Параметры запроса

Ответ

Совпадает с ответом API Создание задачи и получение учётных данных для загрузки (data.modelId и data.params.*).

Пример запроса

{
  "modelId": 100231987
}

Обновление статуса загрузки

Сообщает статус загрузки входных данных. После завершения загрузки этот API нужно вызвать обязательно, иначе моделирование не начнётся.

Endpoint

POST /open-apis/spatial-model/v1/model/upload_status/update

Ограничения

Параметры запроса

Ответ

Возвращается только Единая структура ответа.

Пример запроса

{
  "modelId": 100231987,
  "status": 3,
  "uploadTime": 184620
}

Отмена моделирования

Можно вызывать только для задач, которые находятся в процессе моделирования.

• Отменить можно только задачи в статусе «Моделирование». После отмены задача переходит в статус «Ошибка моделирования».
• При отмене списываются кредиты за уже израсходованный объём; излишне замороженные кредиты возвращаются на баланс.
• Расчёт кредитов обычно занимает несколько минут, но не более примерно 10 минут.

Endpoint

POST /open-apis/spatial-model/v1/model/cancel

Ограничения

Параметры запроса

Ответ

Возвращается только Единая структура ответа.

Пример запроса

{
  "modelId": 100231987
}

Постраничный список задач

Запрашивает задачи моделирования постранично с фильтрами.

Endpoint

POST /open-apis/spatial-model/v1/model/list

Ограничения

Параметры запроса

Ответ

Пример запроса

{
  "modelName": "Design Commune",
  "statusList": [7, 8],
  "startTime": 1790899200000,
  "endTime": 1791763200000,
  "page": {
    "page": 1,
    "limit": 20,
    "order": "DESC"
  }
}

Сведения о задачах

Пакетно запрашивает сведения о задачах моделирования, включая статистику, например длительность моделирования.

Endpoint

POST /open-apis/spatial-model/v1/model/detail

Ограничения

Параметры запроса

Ответ

Пример запроса

{
  "modelIdList": [100231987, 100231988]
}

Кредиты учётной записи

Запрашивает баланс кредитов учётной записи, связанной с appId.

Endpoint

POST /open-apis/spatial-model/v1/credit/info

Ограничения

Параметры запроса

Бизнес-параметров нет. Передайте пустой объект {}.

Ответ

Пример ответа

{
  "code": 0,
  "msg": "success",
  "data": {
    "bizCode": 0,
    "bizMsg": "",
    "availableCredit": 8500,
    "frozenCredit": 1500,
    "totalCredit": 10000
  }
}

Примечание: этот API только запрашивает баланс кредитов учётной записи. Правила списания кредитов за задачи моделирования (момент списания и основание расчёта) будут определены и описаны в следующей версии. В текущей версии значения, которые возвращает этот API, не влияют на вызовы API моделирования.

Скачивание результатов моделирования

Выдаёт временные ссылки для скачивания результатов моделирования. Их состав описан в разделе Результаты моделирования.

Endpoint

POST /open-apis/spatial-model/v1/model/data/download

Ограничения

Параметры запроса

Ответ

Пример запроса

{
  "modelId": 100231987,
  "type": "GLB"
}

Удаление задачи

Удаляет задачу моделирования и связанные с ней данные.

Endpoint

POST /open-apis/spatial-model/v1/model/del

Ограничения

Параметры запроса

Ответ

Возвращается только Единая структура ответа.

Пример запроса

{
  "modelId": 100231987
}

Примечание: удаление необратимо; входные данные и результаты моделирования удаляются вместе с задачей. Добавьте на своей стороне повторное подтверждение.