Información general sobre la API pública de Azure Sphere

  • Artículo

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 de operación y respuestas. Los datos devueltos en la respuesta de la operación tienen 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 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 la recepción de solicitudes y respuestas de operaciones al abstraer gran parte de la complejidad programática de la API pública. Los comandos de la CLI usan la API pública de Azure Sphere para realizar tareas, pero la sencilla sintaxis 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 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 de REST

Una solicitud de API de REST tiene los tres componentes siguientes:

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

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

    Parámetros:

    • colección: una o más 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 interfiera a medida que evolucionan las API.

      Ejemplo: /v2

  2. Campos del encabezado del mensaje de solicitud HTTP:

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

  3. Campos opcionales del cuerpo del mensaje de solicitud HTTP para admitir la operación URI y 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 del encabezado del mensaje de respuesta HTTP:

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

    • Los objetos de respuesta codificados con MIME pueden devolverse en el cuerpo de 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

Antes de 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 maneras en que puede autenticarse.

Tipo de aplicación Descripción Ejemplo Mecanismo de autenticación
Información interactiva del cliente Aplicación del lado cliente basada en GUI Aplicación de Windows enumerando dispositivos Biblioteca de autenticación de Microsoft (MSAL)
JavaScript interactivo Aplicación JavaScript basada en GUI Aplicación de página única 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 compilaciones OAuth 2

Nota

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

Valores de biblioteca de autenticación

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

  • Id. 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
  • Id. de inquilino de Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
  • Extremo de la API Azure Sphere: https://prod.core.sphere.azure.net/

Para obtener más información sobre la autenticación, vea Biblioteca de autenticación de Microsoft (MSAL) y Flujos de autenticación.

Realizar 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
}

Recibir una respuesta

Cada llamada devuelve una respuesta JSON en el siguiente formato:

[{"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 - Mala solicitud
  • 404: no encontrado
  • 409 - Conflicto
  • 410 - Se ha ido
  • 429 - Demasiadas solicitudes
  • 500- Error interno del servidor

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

Instrucciones para el control de errores

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

429 errores: Para proteger los servicios Azure Sphere frente a ataques de denegación de servicio distribuido (DDoS), realizamos un seguimiento de los dispositivos, usuarios o inquilinos que realizan grandes cantidades de llamadas a nuestros servicios y los limitamos. Un mensaje de error 429 indica que el dispositivo, el usuario o el inquilino intentó llamar al servicio Azure Sphere demasiadas veces en un breve período de tiempo. Espere antes de llamar de nuevo al servicio Azure Sphere.

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

Compatibilidad con CORS

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

Contenido relacionado