Azure Sphere 公共 API 概述

项目
09/27/2024

重要

这是 Azure Sphere（旧版）文档。 Azure Sphere（旧版）将于 2027 年 9 月 27 日停用，用户此时必须迁移到 Azure Sphere（集成）。 使用位于 TOC 上方的版本选择器查看 Azure Sphere（集成）文档。

Azure Sphere 公共 API 是一组服务终结点，支持用于创建和管理 Azure Sphere 资源（例如租户、产品、部署和设备组）的 HTTP 操作。 Azure Sphere 公共 API 使用 REST（REpresentational State Transfer）HTTP 协议发送操作请求和响应。操作响应中返回的数据采用 JSON 格式（JavaScript 对象表示法）。可用操作记录在 Azure Sphere 公共 API 参考中。

客户可能更喜欢使用 Azure Sphere 命令行接口（CLI）而不是公共 API 来执行资源管理任务。 CLI 通过抽象化公共 API 的大部分编程复杂性，简化了操作请求和响应的发送和接收。 CLI 命令使用 Azure Sphere 公共 API 来执行任务，但 CLI 命令的简单语法使它们更易于使用。

某些客户可能希望生成自己的用户界面（UI）来执行资源管理任务。 Azure Sphere 公共 API 可用于生成自定义 UI。不能使用 Azure Sphere CLI 生成自定义 UI。

REST API 请求的组件

REST API 请求具有以下三个组件：

请求 URI，格式如下：

VERB https://prod.core.sphere.azure.net/v{version}/{collection}/{id}…[{resourceId} | {collection}]

参数：
- 集合：一个或多个集合。支持多个嵌套集合，因此相对路径可以包含 /collection/id/collection/id ...
  
  示例： /v2/tenants/{tenantId}/devices/{deviceId}/images
- resourceId：特定资源的 ID，用于访问集合中的特定资源。
  
  示例： /v2/tenants/{tenantId}/devicegroups/{devicegroupid}
- 版本：用于标识 API 版本的 API 版本。每个 API 请求都应包含 API 版本，以避免随着 API 的发展而使应用或服务中断。
  
  示例： /v2
HTTP 请求消息标头字段：
- 所需的 HTTP 方法（也称为操作或谓词），它告知该服务你请求的操作类型。
- 指定的 URI 和 HTTP 方法需要的其他标头字段。具体而言，授权标头提供包含请求客户端授权令牌的持有者令牌。
可选的 HTTP 请求消息正文字段以支持 URI 和 HTTP 操作。
- 对于 HTTP POST 或 PUT 操作，正文应在 Content-Type 请求标头和 application/json 中指定。

REST API 响应的组件

REST API 响应具有以下两个组件：

HTTP 响应消息标头字段：
- HTTP 状态代码。成功的调用返回 2xx 代码;4xx 和 5xx 代码是错误状态- 有关详细信息，请参阅 Azure Sphere 公共 API 错误代码部分。或者，可以根据 Azure Sphere 公共 API 引用中指定的方式返回服务定义的状态代码。
- 可选附加标头字段，以支持对请求的响应，例如 Content-Type 响应标头。
可选的 HTTP 响应消息正文字段：
- 可以在 HTTP 响应正文中返回 MIME 编码的响应对象，例如来自返回数据的 GET 方法的响应。这些对象始终以结构化 JSON 格式返回，如 Content-Type 响应标头所指示。

请求身份验证

在发出有效请求之前，必须使用 Azure Sphere 公共 API 对应用程序或服务进行身份验证。下表显示了一些可以进行身份验证的方法。

应用程序类型	说明	示例	身份验证机制
交互式客户端	基于 GUI 的客户端应用程序	Windows 应用枚举设备	Microsoft 身份验证库 (MSAL)
交互式 JavaScript	基于 GUI 的 JavaScript 应用程序	显示设备组部署的 AngularJS 单页应用。	MSAL
交互式 Web	基于 GUI 的 Web 应用程序	显示生成摘要的自定义 Web 仪表板	OAuth 2

注意

Azure Active Directory 平台正在演变为 Microsoft标识平台。有关详细信息，请参阅 Azure Sphere 中的新增功能。

身份验证库值

如果调用Microsoft身份验证库（MSAL）来获取用于身份验证的持有者令牌，则必须提供四个值：

Azure Sphere 客户端应用程序 ID： 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F （身份验证成功需要）
用户的范围： https://sphere.azure.net/api/user_impersonation
Azure Sphere 租户 ID： 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
Azure Sphere API 终结点： https://prod.core.sphere.azure.net/

有关身份验证的详细信息，请参阅 Microsoft身份验证库（MSAL）和身份验证流。

发出请求

使用 Azure Sphere 进行身份验证后，可以发出请求并接收响应。

以下 C# 示例使用 HttpClient 类发出请求。

namespace SpherePublicAPISample
{
    using System;
    using System.Collections.Generic;
    using System.Net.Http;
    using System.Net.Http.Headers;
    using System.Threading;
    using System.Threading.Tasks;
    // You install the Microsoft.Identity.Client reference by using Nuget,
    // starting at https://www.nuget.org/packages/Microsoft.Identity.Client.
    // Follow the instructions to install using Package Manager.
    using Microsoft.Identity.Client;

    class Program
    {
        // Azure Sphere Public API resource URI
        private readonly List<string> Scopes = new List<string>() { "https://sphere.azure.net/api/user_impersonation" };

        // Azure Sphere Public API client application ID.
        private const string ClientApplicationId = "0b1c8f7e-28d2-4378-97e2-7d7d63f7c87f";

        // Azure Sphere Tenant ID.
        public const string Tenant = "7d71c83c-ccdf-45b7-b3c9-9c41b94406d9";

        // Azure Sphere Public API URI
        private static readonly Uri AzureSphereApiUri = new Uri("https://prod.core.sphere.azure.net/");

        // Program entry-point.
        // returns Zero on success, otherwise non-zero.
        private static int Main()
        {
            try
            {
                CancellationTokenSource cancellationTokenSource = new CancellationTokenSource();

                Program program = new Program();

                program.ExecuteAsync(cancellationTokenSource.Token)
                    .GetAwaiter()
                    .GetResult();

                Console.ReadLine();
            }
            catch (Exception ex)
            {
                Console.Error.WriteLine(ex.ToString());
                return -1;
            }
            return 0;
        } // end of main

        private async Task ExecuteAsync(CancellationToken cancellationToken)
        {
            IPublicClientApplication publicClientApp = PublicClientApplicationBuilder
                .Create(ClientApplicationId)
                .WithAuthority(AzureCloudInstance.AzurePublic, Tenant)
                .WithRedirectUri("http://localhost")
                .Build();

            AuthenticationResult authResult = await publicClientApp.AcquireTokenInteractive(Scopes)
                .ExecuteAsync();

            string accessToken = authResult.AccessToken;

            // Call the Azure Sphere API to get tenants available to the authenticated user.
            string result = await GetAsync(accessToken, "v2/tenants", cancellationToken);

            Console.WriteLine(result);
        } // end of ExecuteAsync method

        private async Task<string> GetAsync(string accessToken, string relativeUrl, CancellationToken cancellationToken)
        {
            using (HttpClient client = new HttpClient())
            {
                client.DefaultRequestHeaders.Authorization = new AuthenticationHeaderValue("Bearer", accessToken);

                Uri uri = new Uri(AzureSphereApiUri, relativeUrl);

                using (HttpResponseMessage response = await client.GetAsync(uri, cancellationToken))
                {
                    response.EnsureSuccessStatusCode();
                    return await response.Content.ReadAsStringAsync();
                }
            }
        } // end of GetAsync method

    } // end of class Program
}

接收响应

每个调用以以下格式返回 JSON 响应：

[{"Id":"{tenantId}","Name":"Contoso","Roles":null}]

Azure Sphere 公共 API 错误代码

Azure Sphere 公共 API 返回以下错误代码：

400 - 错误的请求
404 - 未找到
409 - 冲突
410 - 消失
429 - 请求过多
500 - 内部服务器错误

以下部分提供了处理错误的指南。有关特定错误代码的详细信息，请参阅 RFC 7231。

错误处理指南

4xx 错误： 格式不正确的请求可能会导致错误。检查请求语法和正在传递的数据。

429 错误： 为了保护 Azure Sphere 服务免受分布式拒绝服务（DDoS）攻击，我们跟踪并限制对服务进行大量调用的设备、用户或租户。 429 错误消息指示设备、用户或租户在短时间内尝试调用 Azure Sphere 服务过多次。请在再次调用 Azure Sphere 服务之前等待。

500 错误： 偶尔会发生暂时性服务器错误。如果收到服务器错误，请多次重试请求，以查看错误是否消失。

CORS 支持

此版本不支持跨区域源共享（CORS）。

通过

Azure Sphere 公共 API 概述

REST API 请求的组件

REST API 响应的组件

请求身份验证

身份验证库值

发出请求

接收响应

Azure Sphere 公共 API 错误代码

错误处理指南

CORS 支持

反馈

其他资源

通过

Azure Sphere 公共 API 概述

REST API 请求的组件

REST API 响应的组件

请求身份验证

身份验证库值

发出请求

接收响应

Azure Sphere 公共 API 错误代码

错误处理指南

CORS 支持

相关内容

反馈

其他资源