Mitgliedsfreie Ansicht

Startseite Dokumentation & Hilfe
Steamworks-Dokumentation
Web-API – Übersicht

Einführung

Steam stellt eine HTTP-basierte Web-API bereit, mit der Sie auf viele Steamworks-Funktionen zugreifen können. Die API umfasst öffentliche Methoden, die aus jeder Anwendung erreichbar sind, die HTTP-Anfragen senden kann, zum Beispiel Spielclients oder Spielserver. Außerdem enthält die API geschützte Methoden, die eine Authentifizierung erfordern und nur von vertrauenswürdigen Backend-Anwendungen aufgerufen werden sollen.

So werden beispielsweise Web-API-Methoden häufig für die folgenden Zwecke von einem gesicherten Publisherserver verwendet:
  • Verifizieren der Anmeldedaten eines Steam-Nutzers für diesen Server
  • Überprüfen, ob ein Nutzer eine bestimmte Anwendung besitzt
  • Einstellen oder Abrufen der Statistiken, Errungenschaften oder Bestenlistenpunktzahlen eines Nutzers
  • Durchführen eines spielinternen Kaufs

Eine vollständige Liste von allem, was die Steamworks-Web-API bietet, finden Sie im Dokumentationsartikel Referenz zur Steamworks-Web-API.

Anfragenformat

Der Zugriff auf die öffentliche Steamworks-Web-API erfolgt über HTTP-Anfragen (Port 80) oder HTTPS-Anfragen (Port 443) an api.steampowered.com.
Wenn Sie ein Publisher sind, stellt Steam auch einen nur für Partner vorgesehenen Web-API-Server unter https://partner.steam-api.com bereit. Dieser Service dient dem Zweck, eine höhere Verfügbarkeit als der öffentliche Host zu haben. Sie sollten diesen Service für alle Anfragen verwenden, die von Ihren gesicherten Servern aus vorgenommen werden. Lesen Sie den Dokumentationsartikel Web-API-Hostadressen und Vorgehensweisen bei Firewalls für weitere Informationen.

Ähnlich wie die C++-API von Steamworks wurde die Web-API in mehrere Schnittstellen unterteilt, die zugehörige Methoden enthalten. Das URI-Format jeder API-Anfrage lautet:
https://api.steampowered.com/<interface>/<method>/v<version>/

Die meisten Methoden unterstützen eine Liste erforderlicher und optionaler Parameter. Abhängig von der Methode müssen diese Parameter in der Anfrage als GET- oder POST-Parameter übergeben werden.

Übertragen Sie alle Anfragen mit HTTP 1.1 und verwenden Sie möglichst 128-Bit-SSLv3-Verschlüsselung. Der Inhaltstyp muss application/x-www-form-urlencoded sein und die POST-Parameter müssen innerhalb der body-Tags der Anfrage im standardmäßigen URL-Encoding-Format vorliegen. Text muss als UTF-8 übertragen werden.

Authentifizierung

Viele Web-API-Methoden besitzen Zugriffsbeschränkungen, die einen eindeutigen Schlüssel erfordern. Weitere Informationen finden Sie im Dokumentationsartikel Authentifizierung mithilfe von Web-API-Schlüsseln.

Array-Parameter

Manche Methoden erwarten einen Array von Parametern. Dies wird durch ein [0]-Postfix im Parameternamen angegeben. Beim Übergeben von Arrays existiert immer ein count-Parameter, der die Anzahl der Parameter im Array angibt. Beispiel:
?count=2&name[0]=IrgendeinName&name[1]=IrgendeinAndererName

Dienstschnittstellen

Zusätzlich zu den regulären Web-API-Schnittstellen existieren Serviceschnittstellen. Diese Schnittstellen funktionieren sehr ähnlich wie die regulären Schnittstellen; der Hauptunterschied besteht darin, dass alle Service-APIs ihre Argumente nicht nur als GET- oder POST-Parameter, sondern auch als einen einzelnen JSON-String akzeptieren. Rufen Sie zum Übergeben von Daten als einzelnem JSON-String die Web-API-Methode mit dem wie folgt eingestellten Parameter input_json auf:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

Bitte beachten Sie, dass die JSON-Daten URL-codiert sein müssen. Die Felder "key" und "format" sollten wie zuvor weiterhin als separate Parameter übergeben werden. POST-Anfragen werden ebenfalls unterstützt.

Sie können anhand des Namens der Schnittstelle erkennen, ob eine Web-API ein "Service" ist: Wenn dieser Name auf "Service" endet (wie z. B. bei IPlayerService), dann unterstützt sie die zusätzliche Methode des Übergebens von Parameterdaten. Einige Servicemethoden besitzen Parameter, die komplexer strukturiert sind und dieses alternative Eingabeformat erfordern.

Beispielabfrage

In dem folgenden Beispiel werden die 3 neuesten Newseinträge für Team Fortress 2 abgerufen.
Die Anfrage legt fest, dass die Antwort im JSON-Format zurückgegeben werden soll, und enthält Folgendes: Einen erforderlichen App-ID-Parameter (Team Fortress 2 hat die App-ID 440) und einen optionalen Anzahlparameter, um die Anzahl der zurückzugebenen Ergebnisse zu beschränken.

GET /ISteamNews/GetNewsForApp/v2/?appid=440&count=3\r\n Host: api.steampowered.com\r\n Content-Length: 0\r\n\r\n

Mit folgendem Link können Sie diese Abfrage durchführen und ihre Ergebnisse anzeigen:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Weitere Informationen über diesen Aufruf können Sie hier nachlesen: ISteamNews/GetNewsForApp

Abrufen der Steam-ID des Nutzers

Die Steamworks-Web-API identifiziert einzelne Nutzer anhand ihrer eindeutigen 64-Bit-Steam-ID. Informationen darüber, wie Sie die Steam-ID eines Nutzers geschützt abrufen können, finden Sie im Dokumentationsartikel User Authentication and Ownership.

Web-API-Hostadressen und Vorgehensweisen bei Firewalls

Da sich die öffentliche Web-API (api.steampowered.com) hinter dem Edge-Cache von Akamai befindet, variieren die IP-Adressen, die Sie für den Namen sehen werden, basierend auf Ihrem Standort und auf aktuellen Dienständerungen. Die IP-Adressen können sich schnell und fließend ändern; lesen Sie daher weiter, falls Ihre Web-API-Aufrufe durch einen Firewall für abgehende Anfragen gesendet wurden.

Sie sollten den Nur-Partner-Knoten (https://partner.steam-api.com) für alle Anfragen verwenden, die von Ihren gesicherten Servern aus gesendet werden. Dieser Host hat einige andere Eigenschaften als der öffentliche Host:
  • Auf diesen Host kann nur über HTTPS zugegriffen werden.
  • Dieser Host befindet sich nicht hinter dem Edge-Cache von Akamai.
  • Jede Anfrage an diesen Host muss mit Ihrem Publisher-Web-API-Schlüssel durchgeführt werden, selbst Anfragen, die normalerweise keinen Schlüssel erfordern würden. Anfragen, die ohne einen gültigen Publisherschlüssel getätigt werden, geben einen 403-Fehlercode zurück.
  • Anfragen, die 403-Statuscodes generieren, unterliegen strengen Ratenlimits für die sich verbindende IP. Hierdurch wird versucht, eine hohe Verfügbarkeit sicherzustellen. Wenn Sie innerhalb eines bestimmten Zeitintervalls genug Anfragen generieren, die 403-Statuscodes zurückgeben (entweder beim Testen oder durch Verwenden eines regulären Web-API-Schlüssels statt Ihres Publisherschlüssels), wird der Host Ihre IP-Adresse für einige Zeit auf eine Verweigerungsliste setzen.
  • Wenn Sie Anfragen an diesen API-Dienst von einem Host aus senden, bei dem auf abgehende Anfragen ein Firewall-Filter angewendet wird, sollten Sie den DNS-Namen "partner.steam-api.com" zu Ihrer Zulassungsliste hinzufügen. Wenn Ihr Firewall nur numerische Adressen unterstützt, dann fügen Sie den folgenden CIDR-Block zur Zulassungsliste hinzu: 208.64.200.0/22
    HINWEIS: Sie sollten keine Verbindung zu den Web-API-Servern über die IP-Adresse herstellen; bitte verwenden Sie den DNS-Namen. Die Adressen werden nur für diejenigen Clients bereitgestellt, die diese Adressen in ihren Firewalls auf die weiße Liste setzen müssen.