Introducción a la API Azure Sphere pública

La API Azure Sphere pública 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 AZURE SPHERE pública usa el protocolo HTTP REST (transferencia de estado representador) para enviar solicitudes de operación y respuestas. 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 Azure Sphere de api pública.

Es posible que los clientes prefieran usar Azure Sphere interfaz de la línea de comandos (CLI) 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 mediante la abstracción de gran parte de la complejidad programática de la API pública. Los comandos de la CLI usan la API Azure Sphere pública 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 Azure Sphere api pública se puede usar para compilar una interfaz de usuario personalizada. No es posible compilar una interfaz de usuario personalizada con la CLI 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:

   • collection: 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: 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}

   • version: 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 quiebren 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 la operación DE 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 api rest

Una respuesta de api REST tiene los dos componentes siguientes:

1. Campos de encabezado del mensaje de respuesta HTTP:

   • Código de estado HTTP. Las llamadas correctas devuelven códigos 2xx; Los códigos 4xx y 5xx son estados de error; consulte la Azure Sphere códigos de error de api pública para obtener más información. Como alternativa, se puede devolver un código de estado definido por el servicio, tal como se especifica en la Azure Sphere de api pública.
   • 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 opcionales del cuerpo del mensaje de respuesta HTTP:

   • 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 indica 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 Azure Sphere pública. En la tabla siguiente se muestran algunas de las formas de autenticarse.

Valores de la biblioteca de autenticación

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

• Azure Sphere de aplicación cliente: 0b1c8f7e-28d2-4378-97e2-7d7d63f7c87f (necesario para una autenticación correcta)
• Ámbito del usuario: https://sphere.azure.net/api/user_impersonation
• Azure Sphere de inquilino: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
• Azure Sphere punto de conexión de API: https://prod.core.sphere.azure.net/

Para obtener más información sobre la autenticación, vea Azure Active Directory bibliotecas de autenticación y 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
}

Recibir una respuesta

Cada llamada devuelve una respuesta JSON en el formato siguiente:

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

Azure Sphere de error de api pública

La AZURE SPHERE pública devuelve los siguientes códigos de error:

• 400 - Solicitud incorrecta
• 404 - No encontrado
• 409 - Conflicto
• 410 - Ya no está
• 429 - Demasiadas solicitudes
• 500- Error interno del servidor

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

Guía de control de errores

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

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

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

Compatibilidad con CORS

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

Contenido relacionado

• Microsoft Identity Platform 2.0
• Introducción a la API de .NET de AAD