Compartir vía

Introducción a la API pública de Azure Sphere

  • Artículo

Importante

Esta es la documentación de Azure Sphere (heredado). Azure Sphere (heredado) se retira el 27 de septiembre de 2027 y los usuarios deben migrar a Azure Sphere (integrado) en este momento. Use el selector de versiones situado encima de la TOC para ver la documentación de Azure Sphere (integrado).

La API pública de Azure Sphere es un conjunto de puntos de conexión de servicio que admiten operaciones HTTP para crear y administrar recursos de Azure Sphere, como inquilinos, productos, implementaciones y grupos de dispositivos. La API pública de Azure Sphere usa el protocolo HTTP REST (REpresentational State Transfer) para enviar solicitudes y respuestas de operación. Los datos devueltos en la respuesta de la operación tienen el formato JSON (notación de objetos JavaScript). Las operaciones disponibles se documentan en la referencia de API pública de Azure Sphere.

Es posible que los clientes prefieran usar la interfaz de la línea de comandos (CLI) de Azure Sphere en lugar de la API pública para realizar tareas de administración de recursos. La CLI simplifica el envío y recepción de solicitudes y respuestas de operación mediante la abstracción de gran parte de la complejidad mediante programación de la API pública. Los comandos de la CLI usan la API pública de Azure Sphere para realizar tareas, pero la sintaxis simple de los comandos de la CLI hace que sean mucho más fáciles de usar.

Es posible que algunos clientes quieran crear su propia interfaz de usuario (UI) para realizar tareas de administración de recursos. La API pública de Azure Sphere se puede usar para crear una interfaz de usuario personalizada. No es posible crear una interfaz de usuario personalizada con la CLI de Azure Sphere.

Componentes de una solicitud de API REST

Una solicitud de API REST tiene los tres componentes siguientes:

  1. El URI de solicitud, con el formato siguiente:

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

    Parámetros:

    • colección: una o varias colecciones. Se admiten varias colecciones anidadas, por lo que las rutas de acceso relativas pueden incluir /collection/id/collection/id ...

      Ejemplo: /v2/tenants/{tenantId}/devices/{deviceId}/images

    • resourceId: el identificador de un recurso específico, que permite el acceso a recursos específicos dentro de una colección.

      Ejemplo: /v2/tenants/{tenantId}/devicegroups/{devicegroupid}

    • versión: la versión de la API, que identifica la versión de la API. Cada solicitud de API debe incluir una versión de API para evitar que la aplicación o el servicio se interrumpan a medida que evolucionan las API.

      Ejemplo: /v2

  2. Campos de encabezado de mensaje de solicitud HTTP:

    • Método HTTP obligatorio (también denominado " operación" o "verbo"), que indica al servicio qué tipo de operación se está solicitando.
    • Campos de encabezado adicionales, según sea necesario para el URI y el método HTTP especificados. En concreto, un encabezado de autorización que proporciona un token de portador que contiene el token de autorización de cliente para la solicitud.

  3. Campos opcionales del cuerpo del mensaje de solicitud HTTP para admitir el URI y la operación HTTP.

    • Para las operaciones HTTP POST o PUT, el cuerpo debe especificarse en el encabezado de solicitud Content-Type, así como en application/json.

Componentes de una respuesta de la API REST

Una respuesta de la API REST tiene los dos componentes siguientes:

  1. Campos de encabezado de mensaje de respuesta HTTP:

    • Un código de estado HTTP. Las llamadas correctas devuelven códigos 2xx; Los códigos 4xx y 5xx son estados de error; consulte la sección Códigos de error de la API pública de Azure Sphere para más información. Como alternativa, se puede devolver un código de estado definido por el servicio, tal como se especifica en la referencia de API pública de Azure Sphere.
    • Campos de encabezado adicionales opcionales según sea necesario para admitir la respuesta a la solicitud, como un encabezado de respuesta Content-Type.

  2. Campos de cuerpo del mensaje de respuesta HTTP opcionales:

    • Los objetos de respuesta codificados con MIME se pueden devolver en el cuerpo de la respuesta HTTP, como una respuesta de un método GET que devuelve datos. Estos objetos siempre se devuelven en un formato JSON estructurado, como se indica en el encabezado de respuesta Content-Type.

Autenticación de una solicitud

Para poder realizar una solicitud válida, la aplicación o el servicio deben autenticarse con la API pública de Azure Sphere. En la tabla siguiente se muestran algunas de las formas en que puede autenticarse.

Tipo de aplicación Descripción Ejemplo Mecanismo de autenticación
Lado cliente interactivo Aplicación del lado cliente basada en GUI Enumeración de dispositivos de aplicaciones de Windows Biblioteca de autenticación de Microsoft (MSAL)
JavaScript interactivo Aplicación JavaScript basada en GUI Aplicación de página única de AngularJS que muestra implementaciones para un grupo de dispositivos. MSAL
Web interactiva Aplicación web basada en GUI Panel web personalizado que muestra resúmenes de compilación OAuth 2

Nota:

La plataforma Azure Active Directory está evolucionando en la plataforma de identidad de Microsoft. Para más información, consulte Novedades de Azure Sphere.

Valores de la biblioteca de autenticación

Si llama a las bibliotecas de autenticación de Microsoft (MSAL) para adquirir un token de portador que se usará para la autenticación, debe proporcionar cuatro valores:

  • Identificador de aplicación cliente de Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (necesario para la autenticación correcta)
  • Ámbito del usuario: https://sphere.azure.net/api/user_impersonation
  • Identificador de inquilino de Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Punto de conexión de api de Azure Sphere: https://prod.core.sphere.azure.net/

Para obtener más información sobre la autenticación, consulte Microsoft Authentication Library (MSAL) and Authentication flow (Flujos de autenticación).

Realización de una solicitud

Después de autenticarse con Azure Sphere, puede realizar solicitudes y recibir respuestas.

En el siguiente ejemplo de C# se usa la clase HttpClient para realizar una solicitud.

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
}

Recepción de una respuesta

Cada llamada devuelve una respuesta JSON con el formato siguiente:

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

Códigos de error de la API pública de Azure Sphere

La API pública de Azure Sphere devuelve los siguientes códigos de error:

  • 400 - Solicitud incorrecta
  • 404 - No encontrado
  • 409 - Conflicto
  • 410 - Desaparecido
  • 429 - Demasiadas solicitudes
  • 500- Error interno del servidor

En la sección siguiente se proporcionan instrucciones para controlar errores. Para obtener información detallada sobre códigos de error específicos, consulte RFC 7231.

Guía de control de errores

Errores 4xx: las solicitudes con formato incorrecto pueden provocar errores. Compruebe la sintaxis de la solicitud y los datos que se pasan.

Errores 429: para proteger los servicios de Azure Sphere frente a ataques de denegación de servicio distribuidos (DDoS), realizamos un seguimiento y limitamos los dispositivos, los usuarios o los inquilinos que realizan un gran número de llamadas a nuestros servicios. Un mensaje de error 429 indica que el dispositivo, el usuario o el inquilino intentaron llamar al servicio de Azure Sphere demasiadas veces en un breve período de tiempo. Espere antes de volver a llamar al servicio Azure Sphere.

500 errores: En ocasiones, pueden producirse errores transitorios en el servidor. Si recibe un error de servidor, vuelva a intentar la solicitud varias veces para ver si el error desaparece.

Soporte técnico de CORS

El uso compartido de orígenes entre regiones (CORS) no se admite en esta versión.

Contenido relacionado