Informacje dodatkowe o interfejsach API operacji w chmurze

W tym miejscu znajdują się szczegółowe informacje o interfejsach API operacji w chmurze.

W poniższych tematach zawarto kompletną specyfikację OpenAPI na potrzeby interfejsów API. W używanej subskrypcji w chmurze mogą być włączone inne interfejsy API. Aby sprawdzić, które interfejsy API są włączone, należy użyć narzędzia do testowania interfejsów API.

Uzyskiwanie dostępu do narzędzia do testowania interfejsów REST API

Dostęp do interfejsu użytkownika Swagger można uzyskać pod adresem https://hostname/api/explorer, gdzie nazwa_hosta jest nazwą subskrypcji produktu. Na przykład: https://vhost123.mycloud.com/api/explorer. Ten interfejs udostępnia widok, który umożliwia wyświetlenie dostępnych punktów końcowych i ich dokumentacji oraz kliknięcie przycisku Wypróbuj w celu przetestowania każdego punktu końcowego.

Aby uzyskać bezpośredni dostęp do specyfikacji OpenAPI, można użyć następującego wywołania interfejsu REST API:

GET /api/docs

To wywołanie zwraca obiekt JSON zawierający specyfikację OpenAPI interfejsów API, które są włączone w używanej subskrypcji.

Uwierzytelnianie

Wszystkie punkty końcowe wymagają uwierzytelnienia. Można stosować uwierzytelnianie podstawowe z użyciem nazwy użytkownika i hasła swojej subskrypcji w chmurze. Na przykład:

curl https://tenant_name.automationcloud.ibm.com/instance/services/users --user username@company_name.com:password

Uwaga: W interfejsie użytkownika Swagger w niektórych metodach interfejsu REST API może być wyświetlana ikona ostrzeżenia Obraz przedstawia ikonę ostrzeżenia

. Po kliknięciu tego ostrzeżenia zostanie otwarte okno z prośbą o podanie referencji logowania. Jeśli już wcześniej przeprowadzono uwierzytelnianie w portalu w chmurze, nie trzeba ponownie tego robić. Można zignorować to ostrzeżenie.

Alternatywą dla uwierzytelniania podstawowego jest uwierzytelnianie w aplikacji z użyciem referencji usługi. Więcej informacji na ten temat zawiera sekcja Uwierzytelnianie aplikacji klienckich.

Filtrowanie i stronicowanie

Istnieje możliwość używania funkcji stronicowania z metodami eksploracji, które zwracają kolekcje obiektów (np. /users). Domyślnie zwracane są wszystkie elementy kolekcji. Można jednak podać wielkość strony oraz jej numer, aby pobrać tylko podzbiór kolekcji. Na przykład:

curl https://tenant_name.automationcloud.ibm.com/instance/services/users?offset=2&size=20 --user username@company_name.com:password

Kolekcję obiektów można również przefiltrować — w tym celu w wywołaniu należy podać parametry specyficzne dla interfejsu API. Informacje o tym, których parametrów można używać, zawiera dokumentacja każdego interfejsu API.

Błędy

Informacje o powodzeniu lub niepowodzeniu wykonania żądania interfejsu API są przekazywane za pośrednictwem konwencjonalnych kodów odpowiedzi HTTP. W przypadku wystąpienia błędu treść odpowiedzi HTTP zawsze będzie zawierała obiekt błędu JSON z kodem błędu, przyczyną oraz odwołaniem. Na przykład:

{
  "error_number": "CWMGG0006E",
  "error_message": "CWMGG0006E: The value 'username@company_name.com' is invalid for the 'member_id' parameter.",
  "error_message_parameters": [
    "username@company_name.com",
    "member_id"
  ],
  "incident_id": "62d28e96-3059-433a-911d-f9109a7fc93a"
}