Visão geral da API Pública do Azure Sphere

A API pública do Azure Sphere é um conjunto de pontos de extremidade de serviço que dão suporte a operações HTTP para criar e gerenciar recursos do Azure Sphere, como locatários, produtos, implantações e grupos de dispositivos. A API pública do Azure Sphere usa o protocolo HTTP REST (REpresentational State Transfer) para enviar solicitações de operação e respostas. Os dados retornados na resposta da operação são formatados em JSON (JavaScript Object Notation). As operações disponíveis são documentadas na referência da API pública do Azure Sphere.

Os clientes podem preferir usar a interface de linha de comando (CLI) do Azure Sphere em vez da API pública para executar tarefas de gerenciamento de recursos. A CLI simplifica o envio e o recebimento de solicitações e respostas de operação, abstraindo grande parte da complexidade programática da API pública. Os comandos da CLI usam a API pública do Azure Sphere para executar tarefas, mas a sintaxe simples dos comandos da CLI os torna muito mais fáceis de usar.

Alguns clientes podem querer criar sua própria interface do usuário (UI) para executar tarefas de gerenciamento de recursos. A API pública do Azure Sphere pode ser usada para criar uma interface do usuário personalizada. Não é possível criar uma interface do usuário personalizada com a CLI do Azure Sphere.

Componentes de uma solicitação de API REST

Uma solicitação de API REST tem os seguintes três componentes:

1. O URI de solicitação, na seguinte forma:

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

   Parâmetros:

   • coleção: Uma ou mais coleções. Várias coleções aninhadas são suportadas, portanto, os caminhos relativos podem incluir /collection/id/collection/id ...

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

   • resourceId: A ID de um recurso específico, que permite o acesso a recursos específicos dentro de uma coleção.

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

   • version: A versão da API, que identifica a versão da API. Cada solicitação de API deve incluir uma versão de api para evitar que seu aplicativo ou serviço seja interrompido à medida que as APIs evoluem.

     Exemplo: /v2

2. Campos de cabeçalho da mensagem de solicitação HTTP:

   • Um método HTTP necessário (também conhecido como uma operação ou verbo), que informa ao serviço que tipo de operação você está solicitando.
   • Campos de cabeçalho adicionais, conforme exigido pelo método URI e HTTP especificado. Especificamente, um cabeçalho de autorização que fornece um token de portador contendo token de autorização do cliente para a solicitação.

3. Campos opcionais do corpo da mensagem de solicitação HTTP para suportar a operação URI e HTTP.

   • Para operações HTTP POST ou PUT, o corpo deve ser especificado no cabeçalho da solicitação Content-Type, bem como application/json.

Componentes de uma resposta da API REST

Uma resposta de API REST tem os dois componentes a seguir:

1. Campos de cabeçalho da mensagem de resposta HTTP:

   • Um código de status HTTP. Chamadas bem-sucedidas retornam 2xx códigos; Os códigos 4xx e 5xx são status de erro — consulte a seção Códigos de erro da API pública do Azure Sphere para obter detalhes. Como alternativa, um código de status definido pelo serviço pode ser retornado, conforme especificado na referência da API pública do Azure Sphere.
   • Campos de cabeçalho adicionais opcionais conforme necessário para dar suporte à resposta à solicitação, como um cabeçalho de resposta Content-Type.

2. Campos opcionais do corpo da mensagem de resposta HTTP:

   • Objetos de resposta codificados em MIME podem ser retornados no corpo da resposta HTTP, como uma resposta de um método GET que está retornando dados. Esses objetos são sempre retornados em um formato JSON estruturado, conforme indicado pelo cabeçalho de resposta Content-Type.

Autenticação de um pedido

Antes de fazer uma solicitação válida, seu aplicativo ou serviço deve ser autenticado com a API pública do Azure Sphere. A tabela a seguir mostra algumas das maneiras de autenticação.

Valores da biblioteca de autenticação

Se você chamar as bibliotecas de autenticação da Microsoft (MSAL) para adquirir um token de portador para usar para autenticação, você deve fornecer quatro valores:

• ID do aplicativo cliente do Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (necessário para autenticação bem-sucedida)
• Âmbito de aplicação para o utilizador: https://sphere.azure.net/api/user_impersonation
• ID do locatário do Azure Sphere: 7d71c83c-ccdf-45b7-b3c9-9c41b94406d9
• Ponto de extremidade da API do Azure Sphere: https://prod.core.sphere.azure.net/

Para obter mais informações sobre autenticação, consulte Biblioteca de Autenticação da Microsoft (MSAL) e Fluxos de autenticação.

Fazer um pedido

Depois de autenticar com o Azure Sphere, você pode fazer solicitações e receber respostas.

O exemplo C# a seguir usa a classe HttpClient para fazer uma solicitação.

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
}

Receba uma resposta

Cada chamada retorna uma resposta JSON no seguinte formato:

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

Códigos de erro da API pública do Azure Sphere

A API pública do Azure Sphere retorna os seguintes códigos de erro:

• 400 – Pedido Incorreto
• 404 - Não Encontrado
• 409 – Conflito
• 410 - Desaparecido
• 429 - Demasiados pedidos
• 500 - Erro interno do servidor

As orientações para lidar com erros são fornecidas na seção a seguir. Para obter informações detalhadas sobre códigos de erro específicos, consulte RFC 7231.

Orientações para o tratamento de erros

4xx erros: Solicitações malformadas podem levar a erros. Verifique a sintaxe do seu pedido e os dados que estão a ser passados.

429 erros: Para proteger os serviços do Azure Sphere contra ataques distribuídos de negação de serviço (DDoS), rastreamos e limitamos dispositivos, usuários ou locatários que fazem um grande número de chamadas para nossos serviços. Uma mensagem de erro 429 indica que o dispositivo, usuário ou locatário tentou chamar o serviço Azure Sphere muitas vezes em um curto período de tempo. Aguarde antes de chamar o serviço Azure Sphere novamente.

500 erros: Ocasionalmente, erros transitórios do servidor podem ocorrer. Se você receber um erro de servidor, tente novamente a solicitação algumas vezes para ver se o erro desaparece.

Suporte do CORS

O CORS (Compartilhamento de Origem entre Regiões) não é suportado nesta versão.

Conteúdo relacionado

• Plataforma de identidade Microsoft 2.0
• Visão geral da API do AAD .NET