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

  • Artigo

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 (Notação de Objeto JavaScript). As operações disponíveis são documentadas na referência de 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 (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 seguintes três componentes:

  1. O URI de solicitação, no seguinte formulário:

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

    Parâmetros:

    • coleção: uma ou mais coleções. Há suporte para várias coleções aninhadas, para que os caminhos relativos possam 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}

    • versão: 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 ter seu aplicativo ou interrupção de serviço à medida que as APIs evoluem.

      Exemplo: /v2

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

    • Um método HTTP necessário (também conhecido como operação ou verbo), que informa ao serviço qual tipo de operação você está solicitando.
    • Campos de cabeçalho adicionais, conforme exigido pelo método URI e HTTP especificados. 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 dar suporte à operação URI e HTTP.

    • Para operações HTTP POST ou PUT, o corpo deve ser especificado no cabeçalho de solicitação tipo conteúdo, bem como aplicativo/json.

Componentes de uma resposta à API REST

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

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

    • Um código http status. Chamadas bem-sucedidas retornam códigos 2xx; Códigos 4xx e 5xx são status de erro, consulte a seção códigos de erro de API pública do Azure Sphere para obter detalhes. Como alternativa, um código status definido pelo serviço pode ser retornado, conforme especificado na referência de 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 tipo conteúdo.

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

    • Objetos de resposta codificados pelo 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 Tipo de Conteúdo.

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 autenticar.

Tipo de aplicativo Descrição Exemplo Mecanismo de autenticação
Lado interativo do cliente Aplicativo do lado do cliente baseado em GUI Dispositivos de enumeração do aplicativo Windows MSAL (Biblioteca de Autenticação da Microsoft)
JavaScript interativo Aplicativo JavaScript baseado em GUI Aplicativo de página única do AngularJS que exibe implantações para um grupo de dispositivos. MSAL
Web interativa Aplicativo Web baseado em GUI Web dashboard personalizado exibindo resumos de build OAuth 2

Nota

A plataforma do Azure Active Directory está evoluindo para a plataforma Microsoft Identity. Para obter mais informações, confira Novidades no Azure Sphere.

Valores da biblioteca de autenticação

Se você chamar a 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ária 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 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 de API pública do Azure Sphere

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

  • 400 – Solicitação incorreta
  • 404 – Não encontrado
  • 409 – Conflito
  • 410 - Ido
  • 429 – Muitas solicitações
  • 500 – Erro interno do servidor

As diretrizes para o tratamento de 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.

429 erros: Para proteger os serviços do Azure Sphere contra ataques DDoS (negação de serviço) distribuídos, 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, o usuário ou o locatário tentaram 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.

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

Suporte ao CORS

O CORS (Compartilhamento de Origem Entre Regiões) não tem suporte nesta versão.

Conteúdo relacionado