Implementowanie niestandardowego punktu końcowego REST Server-Side

 

Dotyczy: Windows Azure Pack

Po stronie serwera udostępnia zestaw interfejsów API REST, które są wywoływane przez klienta zarówno w celu pobierania danych, jak i wykonywania operacji. Oba te typy operacji zwykle są wywoływane na zapleczu w celu pobrania rzeczywistych danych lub wykonania rzeczywistej operacji. Kontroler, który implementuje interfejs API, jest zwykle ASP.NET kontroler MVC zwraca kod JSON, a zaplecze będzie zwykle interfejsem API zarządzania usługami, ale może być dowolną inną usługą dostępną z witryny internetowej ASP.NET MVC.

Ważne

Przykład Hello world zawiera przykładową implementację po stronie serwera.

Zarówno po stronie klienta, jak i po stronie serwera mogą znajdować się w tym samym projekcie Visual Studio i są wdrażane w tych samych portalach zarządzania.

Klasa kontrolera

Klasa kontrolera jest wystąpieniem jednej z ASP.NET klasy abstrakcyjnej MVC w warstwie Standardowa Controller lub AsyncController. Zazwyczaj będzie ona oznaczona atrybutami [RequireHttps], aby upewnić się, że dozwolone są tylko bezpieczne połączenia, [OutputCache] uniemożliwić buforowanie odpowiedzi i [PortalExceptionHandler], który został opisany w poniższej sekcji Obsługa błędów . Aby zapobiec atakom wyłudzającymi informacje, metody w kontrolerze są oznaczone ciągiem [HttpPost]. Nie zezwala to na żądania HTTP GET podczas zezwalania na żądania HTTP POST. Ani struktury po stronie klienta, ani serwera nie nakładają żadnych ograniczeń na to, jak strony serwera i klienta komunikują się ze sobą, z wyjątkiem tego, gdzie wymagana jest interakcja z widżetem siatki platformy po stronie klienta. W takim przypadku zobacz następującą sekcję Zwracanie zestawów danych .

Zwracanie zestawów danych

Zestaw danych to lista danych, które mają być wyświetlane przez interfejs użytkownika, zazwyczaj na liście (widok siatki). Różni się ona od standardowej odpowiedzi, ponieważ platforma po stronie klienta obsługuje pobieranie i wyświetlanie jej w siatce. Jeśli metoda zwraca zestaw danych, zazwyczaj reprezentowany w interfejsie użytkownika jako listę, zaleca się użycie metody Controller.JsonDataSet, jak w poniższym przykładzie:

return this.JsonDataSet(listOfData);

Spowoduje to automatyczne zawijanie zestawu danych listOfData w otoce JSON odpowiedniej do przetwarzania przez strukturę po stronie klienta. Aby uzyskać informacje na temat implementacji po stronie klienta, zobacz How to Display a Grid in a Windows Azure Pack Management Portal Extension (Jak wyświetlić siatkę w rozszerzeniu portalu administracyjnego pakietu Azure Pack).

Wykonywanie poleceń

Metody wykonujące polecenia w kontrolerze zwykle zwracają obiekt JSON, aby pokazać, że operacja zadziałała. Może to być tak proste, jak wartość logiczna oznaczająca powodzenie lub tak złożone, jak dane, które uległy zmianie w wyniku operacji. Nic jednak nie jest rzeczywiście wymagane przez platformy po stronie klienta ani serwera.

Obsługa błędów

Wyjątki, które są zgłaszane przez kontroler, zazwyczaj muszą być wyświetlane użytkownikowi w celu wykonania dalszych działań lub kontynuacji. Najprostszym sposobem wykonania tej czynności po stronie serwera jest zastosowanie atrybutu [PortalExceptionHandler] do klasy. Wszelkie wyjątki typu PortalException zostaną przetłumaczone na poprawnie modelowany kod JSON, mają odpowiedni zestaw kodów błędów HTTP i zostaną zwrócone po stronie klienta w celu łatwego wyświetlania z powiadomieniem o błędzie. Poniżej znajduje się przykładowy kod JSON zwrócony po błędzie z atrybutem [PortalExceptionHandler]:

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

Każdy inny typ wyjątku będzie wyświetlany jako pusty błąd HTTP 500, aby uniknąć uwidaczniania wewnętrznych szczegółów dla użytkownika. Ponadto ślady stosu będą wysyłane tylko wtedy, gdy portal, w którym uruchomiono rozszerzenie, ma ustawioną wartość true. Można to zmienić w pliku web.config portalu zarządzania. Aby uzyskać więcej informacji, zobacz sekcję Interfejs użytkownika błędów zwracanych z wywołań interfejsu API.

Zobacz też

Windows rozszerzenia interfejsu użytkownika portalu administracyjnego pakietu Azure Pack
How to Display a Grid in a Windows Azure Pack Management Portal Extension (Jak wyświetlić siatkę w rozszerzeniu portalu zarządzania pakietu azure)
Debugowanie rozszerzenia portalu zarządzania pakietu Windows Azure Pack