Implementando um ponto de extremidade REST de Server-Side personalizado

Artigo
08/24/2015

Aplica-se a: Windows Azure Pack

O lado do servidor fornece um conjunto de APIs REST que são chamadas pelo lado do cliente para recuperar dados e executar operações. Esses dois tipos de operação normalmente chamarão um back-end para obter os dados reais ou executarão a operação real. O controlador, que é o que implementa a API, geralmente é um controlador MVC ASP.NET retornando JSON, e o back-end normalmente será a API de Gerenciamento de Serviços, mas pode ser qualquer outro serviço acessível em um site do ASP.NET MVC.

Importante

O exemplo de Olá, Mundo fornece uma implementação do lado do servidor de exemplo.

Tanto o lado do cliente quanto o lado do servidor podem residir no mesmo projeto de Visual Studio e são implantados nos mesmos portais de gerenciamento.

Classe Controller

A classe de controlador é uma instância de uma das classes abstratas padrão do ASP.NET MVC Controlador ou AsyncController. Normalmente, ele será marcado com os atributos [RequireHttps] para garantir que somente conexões seguras sejam permitidas, [OutputCache] para não permitir o cache de respostas e [PortalExceptionHandler], que é descrito na seguinte seção Manipulando Erros . Para evitar ataques de phishing, os métodos no controlador são marcados com [HttpPost]. Isso não permite solicitações HTTP GET ao permitir solicitações HTTP POST. Nem as estruturas do lado do cliente nem do servidor colocam restrições sobre como o servidor e os lados do cliente conversam entre si, com exceção de onde a interação com o widget grid da estrutura do lado do cliente é necessária. Nesse caso, consulte a seguinte seção Retornando conjuntos de dados .

Retornando conjuntos de dados

Um conjunto de dados é uma lista de dados a serem mostrados pela interface do usuário, normalmente em uma lista (exibição de grade). É diferente de uma resposta padrão em que a estrutura do lado do cliente manipula a recuperação e exibi-la em uma grade. Se um método estiver retornando um conjunto de dados, normalmente representado na interface do usuário como uma lista, é recomendável usar o método Controller.JsonDataSet como no exemplo a seguir:

return this.JsonDataSet(listOfData);

Isso encapsula automaticamente o conjunto de dados listOfData em um wrapper JSON adequado para processamento pela estrutura do lado do cliente. Para obter informações sobre a implementação do lado do cliente, consulte How to Display a Grid in a Windows Azure Pack Management Portal Extension.

Executando comandos

Os métodos que executam comandos no controlador geralmente retornarão um objeto JSON para mostrar que a operação funcionou. Isso pode ser tão simples quanto um êxito booliano ou tão complexo quanto os dados que foram alterados como resultado da operação. Nada, porém, é realmente exigido pelas estruturas do cliente nem do lado do servidor.

Manipulando erros

As exceções geradas pelo controlador geralmente precisam ser mostradas ao usuário para mais ações ou acompanhamento. A maneira mais fácil de fazer isso no lado do servidor é aplicar o atributo [PortalExceptionHandler] à sua classe. Todas as exceções do tipo PortalException serão convertidas em JSON modelada corretamente, terão o código de erro HTTP apropriado definido e serão retornadas para o lado do cliente para exibição fácil com uma notificação de erro. Um exemplo do JSON retornado por erro com o atributo [PortalExceptionHandler] está abaixo:

{
  "message": "Fake Error",
  "ErrorMessage": "Fake Error",
  "httpStatusCode": "InternalServerError",
  "operationTrackingId": null,
  "stackTrace": null,
}

Qualquer outro tipo de exceção será mostrado como um erro HTTP 500 vazio, para evitar expor detalhes internos ao usuário. Além disso, os rastreamentos de pilha só serão enviados se o portal no qual a extensão está em execução tiver DevelopmentMode definido como true. Isso pode ser alterado no arquivo de web.config do portal de gerenciamento. Para obter mais informações, consulte a interface do usuário da seção para erros retornados de chamadas de API.

Consulte Também

Windows Extensões de Interface do Usuário do Portal de Gerenciamento do Azure Pack
Como exibir uma grade em uma extensão do portal de gerenciamento do Azure Pack Windows
Depurando uma extensão do portal de gerenciamento do Azure Pack Windows

Compartilhar via