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 e respostas de operação. Os dados retornados na resposta da operação são formatados em JSON (JavaScript Object Notation). As operações disponíveis estão documentadas na referência da API pública do Azure Sphere.

Os clientes podem preferir usar a CLI (interface de linha de comando) 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 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 três componentes a seguir:

1. O URI da solicitação, no seguinte formato:

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

   Parâmetros:

   • collection: 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 em 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 obrigatório (também conhecido como uma operação ou um verbo), que indica ao serviço que tipo de operação está sendo solicitada.
   • 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 o token de autorização do cliente para a solicitação.

3. Campos opcionais do corpo da mensagem de solicitação HTTP para dar suporte à 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 da 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 códigos 2xx; 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 de 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 uma solicitação

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 pelas quais você pode se autenticar.

Valores da biblioteca de autenticação

Se você chamar as MSAL (Bibliotecas de Autenticação da Microsoft) para adquirir um Token de Portador a ser usado para autenticação, deverá fornecer quatro valores:

• ID do aplicativo cliente do Azure Sphere: 0B1C8F7E-28D2-4378-97E2-7D7D63F7C87F (necessário para autenticação bem-sucedida)
• Escopo para o usuário: 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 MSAL (Biblioteca de Autenticação da Microsoft) e Fluxos de autenticação.

Fazer uma solicitação

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

O exemplo de 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
}

Receber 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 - solicitação inválida
• 404 – não encontrado
• 409 - Conflito
• 410 - Desapareceu
• 429 - Muitos Pedidos
• 500 - Erro interno do servidor

As diretrizes 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.

Diretrizes de tratamento de erros

Erros 4xx: solicitações malformadas podem levar a erros. Verifique a sintaxe da solicitação e os dados que estão sendo passados.

Erros 429: para proteger os serviços do Azure Sphere contra ataques de DDoS (negação de serviço distribuído), 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 do Azure Sphere muitas vezes em um curto período de tempo. Aguarde antes de chamar o serviço do Azure Sphere novamente.

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

Suporte a CORS

O compartilhamento de origem entre regiões (CORS) não é suportado nesta versão.

Conteúdo relacionado

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