Wprowadzenie

Steam posiada WebAPI oparte na HTTP, które może być używane do uzyskiwania dostępu do wielu funkcji Steamworks. To API zawiera publiczne metody, do których może uzyskać dostęp dowolna aplikacja zdolna do wysłania żądań HTTP, np. klient gry lub serwer. Zawiera ono również chronione metody, które wymagają uwierzytelniania i do których dostęp powinien być uzyskiwany za pomocą zaufanych aplikacji back-endu.

Przykładowo, metody WebAPI są zazwyczaj używane przez bezpieczny serwer wydawcy, by:

• zweryfikować dane użytkownika Steam na tym serwerze;
  
• sprawdzić, czy użytkownik posiada daną aplikację;
  
• zapisać lub odzyskać dane użytkownika dotyczące statystyk, osiągnięć i wyników w tabelach;
  
• dokonać zakupu w grze.

Pełna lista dostępnych funkcji oferowanych przez WebAPI Steamworks znajduje się tutaj.

Format żądania

Dostęp do publicznego API webowego Steamworks można uzyskać poprzez wysłanie żądania HTTP (port 80) lub HTTPS (port 443) do api.steampowered.com.
Jeśli jesteś wydawcą, Steam zapewnia również serwer API webowego tylko dla partnerów, hostowany pod adresem https://partner.steam-api.com. Celem tej usługi jest większa dostępność w porównaniu z publicznym hostem; należy jej używać do wszystkich żądań wysyłanych z bezpiecznych serwerów. Dodatkowe informacje znajdziesz tutaj.

Podobnie jak API C++ Steamworks, Web API jest podzielone na wiele interfejsów, które zawierają powiązane metody. Format URI każdego żądania API to:
Większość metod obsługuje listę wymaganych i opcjonalnych parametrów. W zależności od metody te parametry muszą zostać przekazane w żądaniu jako GET albo POST.

Wszystkie żądania muszą być wysyłane przez HTTP 1.1 oraz powinny korzystać z bezpiecznego połączenia TLS, gdy jest to możliwe. Typ zawartości (Content-Type) musi być określony jako application/x-www-form-urlencoded, a parametry POST muszą być zawarte w treści żądania w standardowym formacie kodowania URL. Tekst musi być przesłany jako UTF-8.

Uwierzytelnianie

Dostęp do wielu metod Web API jest ograniczony, a do ich użycia wymagany jest unikalny klucz. Więcej informacji znajduje się tutaj.

Tablice parametrów

Niektóre metody oczekują tablic parametrów. Jest to określane poprzez przyrostek [0] w nazwie parametru. Podczas przesyłania tablic zawsze obecny będzie parametr count, który określa liczbę parametrów w tablicy, np.

Interfejsy usług

Oprócz standardowych wywołań interfejsu sieci istnieją również interfejsy usługi. Te interfejsy działają bardzo podobnie do zwykłych interfejsów, a podstawową różnicą jest to, że wszystkie interfejsy usług akceptują swoje argumenty jako pojedynczy obiekt blob JSON. Dodatkowo będą przyjmować je jako parametry GET lub POST. Aby przesłać dane w formacie JSON, wywołaj metodę web API z parametrem input_json tak jak w poniższym przykładzie:

Pamiętaj, że JSON musi być zakodowany jako adres URL. Pola „key” i „format” powinny być przekazywane jako osobne parametry, tak jak to miało miejsce wcześniej. Obsługiwane są również żądania w formacie POST.

Możesz określić, czy WebAPI jest usługą po nazwie interfejsu. Jeśli kończy się ona na „Service”, np. IPlayerService, to obsługuje ona ww. dodatkową metodę przekazywania danych parametrów. Niektóre metody usług mają parametry o bardziej złożonej strukturze, a wspomniany wyżej alternatywny format wprowadzania jest przez nie wymagany.

Przykład zapytania

W poniższym przykładzie zapytanie zwraca 3 najnowsze wiadomości dla Team Fortress 2.
W żądaniu określono, że odpowiedź musi być w formacie JSON i zawierać wymagany parametr „appid” (identyfikator aplikacji Team Fortress 2 to 440) oraz opcjonalny parametr „count” ograniczający liczbę zwróconych wyników.


Możesz wykonać to zapytanie i zobaczyć jego rezultat poprzez ten link:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Możesz przeczytać więcej o tym zapytaniu tutaj: ISteamNews/GetNewsForApp.

Uzyskiwanie ID Steam użytkownika

Interfejs sieciowy Steamworks identyfikuje poszczególnych użytkowników poprzez ich unikalne 64-bitowe ID Steam. Aby poznać, jak bezpiecznie uzyskać ID Steam użytkownika, przeczytaj ten artykuł.

Adresy hosta Web API i uwagi dotyczące zapory

Publiczny interfejs Web API (api.steampowered.com) znajduje się za serwerem regionalnym treści firmy Akamai, więc adresy IP, które zobaczysz dla danej nazwy, będą różnić się w zależności od twojej lokalizacji oraz wprowadzanych zmianach w działaniu usługi. Adresy IP zmieniać się szybko i często, więc jeśli wywołania Web API dla żądań wychodzących są wykonywane przez zaporę, czytaj dalej.

Do wszystkich żądań wykonanych z pomocą twoich zabezpieczonych serwerów należy używać węzłów dostępnych tylko dla partnerów (https://partner.steam-api.com). Wspomniany host ma trochę inne właściwości niż host publiczny:

• Ten host jest dostępny tylko przez HTTPS.
  
• Ten host nie znajduje się za serwerem regionalnym treści firmy Akamai.
  
• Każde żądanie do tego hosta musi zostać wykonane przy użyciu klucza Web API wydawcy, nawet jeśli żądania zwyczajowo nie wymagałyby żadnego klucza. Żądania złożone bez prawidłowego klucza wydawcy zwrócą kod błędu 403.
  
• Żądania generujące kody błędu 403 (zazwyczaj dzieje się tak przy korzystaniu ze zwykłego klucza Web API zamiast klucza wydawcy) spowodują nałożenie rygorystycznego ograniczenia połączeń dla adresu IP, które wysyła takie żądania. Ma to na celu zapewnienie wysokiej dostępności.
  
• Jeśli będziesz przesyłać żądania do tej usługi interfejsu z hosta, na którym zastosowano filtr zapory na żądania wychodzące, to musisz dodać nazwę DNS-a „partner.steam-api.com” do listy dozwolonych. Jeśli twoja zapora internetowa działa tylko z adresami numerycznymi, dodaj następujący blok CIDR do listy dozwolonych: 208.64.200.0/22.
  UWAGA: nie należy łączyć się z serwerami WebAPI przy użyciu IP. Użyj nazwy DNS-a. Te adresy są przyznawane jedynie tym klientom, którzy muszą umieścić je na białej liście ich zapór internetowych.

Biała lista adresów IP

Umożliwiamy dodawanie adresów IP dla wywołań interfejsu WebAPI do białej listy. Jest to dodatkowa warstwa ochrony na wypadek, gdyby twój klucz WebAPI wpadł w niepowołane ręce. Dzięki temu akceptowane są tylko wywołania interfejsu WebAPI z dozwolonych adresów IP. Kiedy dowolny adres IP zostanie dodany do białej listy, wszelkie żądania z adresów spoza listy zostaną zablokowane i zwrócą odpowiedź: 403 – Dostęp zabroniony.

Dodawanie adresów IP do białej listy jest proste. Na stronie dowolnej grupy, która ma klucz WebAPI, kliknij przycisk „Zarządzaj kluczem WebAPI” i postępuj zgodnie z instrukcjami.

Każdy klucz WebAPI ma własną białą listę, a dodanie innych adresów IP nie jest wymagane.

Uwaga: dodanie do białej listy nie gwarantuje bezpieczeństwa klucza WebAPI. Chroń swój klucz i nie udostępniaj go nikomu, a jeśli zostanie ujawniony, zmień go natychmiast.