你当前正在访问 Microsoft Azure Global Edition 技术文档网站。 如果需要访问由世纪互联运营的 Microsoft Azure 中国技术文档网站,请访问 https://docs.azure.cn

Data - Download Preview

数据下载 API

适用于: S1 定价层。

此 API 允许调用方下载以前上传的数据内容。

可以在一种方案中使用此 API,例如下载以前使用数据上传 API 上传的现有地理围栏集合,以便在Azure Maps地理围栏服务中使用。

提交下载请求

若要下载内容,将使用 GET 请求,其中路径将包含 udid 要下载的数据。 (可选)还可以传入 Accept 标头以指定数据响应的首选项 Content-Type
例如,若要下载以前使用上传 API 上传的地理围栏集合, udid 请将之前在上传 API 响应中接收的数据的路径 udid 中的参数设置为 Accept 以下任一媒体类型:

  • application/json
  • application/vnd.geo+json
  • application/octet-stream

下载数据响应

如果找到具有传入udid的数据资源,则下载 API 将返回 HTTP 200 OK 响应,其中响应正文将包含数据资源的内容。
如果未找到具有传入udid的数据资源,将返回 HTTP 400 Bad Request 错误响应。

下面是使用上传 API 上传的 GeoJSON 简单地理围栏的示例响应正文:

{
    "type": "FeatureCollection",
    "features": [{
        "type": "Feature",
        "geometry": {
            "type": "Point",
            "coordinates": [-122.126986, 47.639754]
        },
        "properties": {
            "geometryId": "001",
            "radius": 500
        }
    }]
}
GET https://{geography}.atlas.microsoft.com/mapData/{udid}?api-version=1.0
GET https://{geography}.atlas.microsoft.com/mapData/{udid}?subscription-key={subscription-key}&api-version=1.0

URI 参数

Name In Required Type Description
geography
path True
  • string

此参数指定Azure Maps Creator 资源所在的位置。 有效值是我们和欧盟。

udid
path True
  • string

内容的唯一数据 ID。 udid必须已从成功的数据上传 API 调用中获取。

api-version
query True
  • string

Azure Maps API 的版本号。 当前版本为 1.0

subscription-key
query
  • string

从 Azure Maps 帐户提供的 Azure Maps 密钥之一。 有关如何管理身份验证的详细信息,请参阅 本文

请求头

Name Required Type Description
x-ms-client-id
  • string

指定哪个帐户旨在与 Azure AD 安全模型结合使用。 它表示Azure Maps帐户的唯一 ID,可以从Azure Maps管理平面帐户 API 检索。 若要在Azure Maps中使用 Azure AD 安全性,请参阅以下文章以获取指导。

响应

Name Type Description
200 OK
  • object

数据下载请求成功完成。 响应正文将包含传入 udid的内容。

Headers

  • Content-Type: string
400 Bad Request

错误请求:一个或多个参数未正确指定或互斥。

401 Unauthorized

由于订阅密钥无效或 Azure Active Directory (Azure AD) 持有者令牌而拒绝访问。 确保为活动的 Azure 订阅和 Maps 资源提供有效的密钥。 否则,请验证 WWW-Authenticate 标头以获取提供的 Azure AD 持有者令牌的错误代码和说明。

Headers

  • WWW-Authenticate: string
403 Forbidden

权限、容量或身份验证问题。

404 Not Found

找不到:找不到请求的资源,但将来可能再次可用。

500 Internal Server Error

处理该请求时出错。 请稍后再试。

安全性

AADToken

这些是 Azure Active Directory OAuth2 流。 与 Azure 基于角色的访问控制配对时,它可用于控制对 Azure Maps REST API 的访问。 Azure 基于角色的访问控制用于指定对一个或多个Azure Maps资源帐户或子资源的访问。 任何用户、组或服务主体都可以通过内置角色或由一个或多个权限组成的自定义角色授予访问权限,以Azure Maps REST API。

若要实现方案,建议查看 身份验证概念。 总之,此安全定义提供了一种解决方案,用于通过能够针对特定 API 和范围进行访问控制的对象对应用程序 () 建模。

说明

  • 此安全定义需要使用x-ms-client-id标头来指示应用程序请求访问哪些Azure Maps资源。 可以从 地图管理 API 获取此功能。

Authorization URL特定于 Azure 公有云实例。 主权云具有唯一的授权 URL 和 Azure Active Directory 配置。 * Azure 基于角色的访问控制是通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 从 Azure 管理平面配置的。 * 使用 Azure Maps Web SDK 允许为多个用例配置基于应用程序的设置。

  • 目前,Azure Active Directory v1.0 或 v2.0 支持工作、学校和来宾,但不支持个人帐户。

Type: oauth2
Flow: implicit
Authorization URL: https://login.microsoftonline.com/common/oauth2/authorize

Scopes

Name Description
https://atlas.microsoft.com/.default https://atlas.microsoft.com/.default

subscription-key

这是在Azure 门户或使用 PowerShell、CLI、Azure SDK 或 REST API 中创建Azure Maps帐户时预配的共享密钥。

使用此密钥,任何应用程序都可以访问所有 REST API。 换句话说,此密钥可用作颁发密钥的帐户中的主密钥。

对于公开的应用程序,建议使用机密客户端应用程序方法来访问 Azure Maps REST API,以便安全地存储密钥。

Type: apiKey
In: query

SAS Token

这是通过 Azure 管理平面通过 Azure 门户、PowerShell、CLI、Azure SDK 或 REST API 在Azure Maps资源上的列表 SAS 操作创建的共享访问签名令牌。

使用此令牌时,任何应用程序都有权使用 Azure 基于角色的访问控制进行访问,并精细控制特定令牌的过期、速率和区域 () 。 换句话说,SAS 令牌可用于允许应用程序以比共享密钥更安全的方式控制访问。

对于公开的应用程序,建议在 地图帐户资源 上配置允许的源的特定列表,以限制呈现滥用,并定期续订 SAS 令牌。

Type: apiKey
In: header

示例

Download previously uploaded GeoJSON data containing geometries that represent a collection of geofences

Sample Request

GET https://us.atlas.microsoft.com/mapData/25084fb7-307a-4720-8f91-7952a0b91012?subscription-key=[subscription-key]&api-version=1.0

Sample Response

{
  "type": "FeatureCollection",
  "features": [
    {
      "type": "Feature",
      "geometry": {
        "type": "Point",
        "coordinates": [
          -122.126986,
          47.639754
        ]
      },
      "properties": {
        "geometryId": "001",
        "radius": 500
      }
    }
  ]
}
{
  "error": {
    "code": "400 BadRequest",
    "message": "Bad request: one or more parameters were incorrectly specified or are mutually exclusive."
  }
}
{
  "error": {
    "code": "401 Unauthorized",
    "message": "Access denied due to invalid subscription key. Make sure to provide a valid key for an active subscription."
  }
}
{
  "error": {
    "code": "403 Forbidden",
    "message": "Permission, capacity, or authentication issues."
  }
}
{
  "error": {
    "code": "404 NotFound",
    "message": "Not Found: the requested resource could not be found, but it may be available again in the future."
  }
}
{
  "error": {
    "code": "500 InternalServerError",
    "message": "An error occurred while processing the request. Please try again later."
  }
}

定义

ODataError

当Azure Maps API 中发生错误时,将返回此对象。

ODataErrorResponse

当Azure Maps API 中发生错误时,将返回此响应对象。

ODataError

当Azure Maps API 中发生错误时,将返回此对象。

Name Type Description
code
  • string

ODataError 代码。

details

当Azure Maps API 中发生错误时,将返回此对象。

message
  • string

如果可用,则为错误的人工可读说明。

target
  • string

如果可用,则导致错误的目标。

ODataErrorResponse

当Azure Maps API 中发生错误时,将返回此响应对象。

Name Type Description
error

当Azure Maps API 中发生错误时,将返回此对象。