Tài liệu Steamworks
Tổng quan về Web API

Giới thiệu

Steam đưa ra một API web dựa trên HTTP để truy cập một số tính năng của Steamworks. API chứa các phương thức công khai có thể được truy cập từ bất kỳ ứng dụng nào có khả năng thực hiện yêu cầu HTTP, như máy khách hoặc máy chủ trò chơi. API cũng chứa các phương thức được bảo vệ, bắt buộc phải xác thực và truy cập từ các ứng dụng backend chứng nhận tin cậy.

Ví dụ, máy chủ bảo mật của nhà phát hành thường sử dụng các phương thức API web để:
  • Xác thực thông tin đăng nhập của người dùng Steam với máy chủ đó
  • Kiểm tra xem người dùng có sở hữu một ứng dụng cụ thể không
  • Đặt hoặc lấy dữ liệu người dùng, thành tựu, và điểm số trên bảng thành tích
  • Thực hiện lệnh mua hàng trong trò chơi

Bạn có thể xem danh sách đầy đủ mọi thứ do API Web Steamworks cung cấp tại Tham khảo API Web Steamworks.

Yêu cầu định dạng

API Web Steamworks được truy cập công khai bằng cách gửi lệnh HTTP (cổng 80) hoặc HTTPS (cổng 443) tới api.steampowered.com.
Nếu bạn là nhà phát hành, Steam sẽ cung cấp thêm một máy chủ API Web chỉ dành cho đối tác được host tại https://partner.steam-api.com. Mục đích của dịch vụ là cung cấp tính khả dụng cao hơn máy chủ công cộng; bạn nên dùng dịch vụ này cho mọi yêu cầu gửi từ máy chủ bảo mật của mình. Xem Địa chỉ host API Web, các cân nhắc về tường lửa để biết thêm thông tin.

Tương tự như API Steamworks C++, API Web được chia thành nhiều interface chứa các phương thức liên quan. Định dạng URI của mỗi yêu cầu API là:
https://api.steampowered.com/<interface>/<method>/v<version>/

Đa số phương thức hỗ trợ một danh sách tham số bắt buộc và không bắt buộc. Tùy thuộc từng phương thức, các tham số này phải được truyền qua phương thức GET hoặc POST trong yêu cầu.

Nếu được, tất cả yêu cầu nên được gửi bằng HTTP 1.1 và sử dụng giao thức bảo mật TLS. Content-Type phải là application/x-www-form-urlencoded và tham số POST phải thuộc phần nội dung của yêu cầu ở định dạng urlencoding tiêu chuẩn. Văn bản cần được truyền đi dưới định dạng UTF-8.

Xác thực

Nhiều phương thức API Web có các hạn chế truy cập, yêu cầu một mã không trùng khớp, xem Xác thực bằng khóa API Web để biết thêm chi tiết.

Tham số mảng

Vài phương thức yêu cầu mảng tham số. Điều này được xác định bởi hậu tố [0] trong tên tham số. Khi truyền mảng, luôn có tham số count để chỉ định bao nhiêu tham số trong mảng. Ví dụ:
?count=2&name[0]=SomeNameHere&name[1]=SomeOtherName

Interface của dịch vụ

Ngoài lệnh gọi API Web thông thường là các interface của dịch vụ. Interface này hoạt động rất giống với interface thông thường, điểm khác biệt chính nằm ở chỗ tất cả API dịch vụ sẽ chấp nhận các đối số là một blob JSON đơn lẻ bên cạnh việc xem đó là những tham số GET hay POST. Để truyền dữ liệu dưới dạng JSON, hãy gọi phương thức API Web với tham số input_json được đặt là:
?key=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&input_json={"steamid":76561197972495328}

Lưu ý rằng JSON sẽ cần URL đã mã hóa theo định dạng. Mục "key" và "format" nên truyền đi như hai tham số tách biệt như trước đây. Yêu cầu POST cũng được hỗ trợ.

Bạn có thể biết API Web là "dịch vụ" hay không thông qua tên interface; nếu kết thúc bằng "Service" như IPlayerService, thì nó hỗ trợ thêm phương thức truyền dữ liệu tham số. Vài phương thức "dịch vụ" có tham số với cấu trúc phức tạp hơn và yêu cầu định dạng đầu vào thay thế này.

Ví dụ về truy vấn

Ví dụ bên dưới truy xuất 3 mục tin tức Team Fortress 2 gần đây nhất.
Yêu cầu xác định phản hồi nên được trả về dưới dạng JSON và bao gồm: một tham số AppID bắt buộc (AppID của Team Fortress 2 là 440), và tham số số lượng không bắt buộc để giới hạn số kết quả trả về.

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

Bạn có thể thực thi và xem kết quả truy vấn bằng liên kết sau:
https://api.steampowered.com/ISteamNews/GetNewsForApp/v2/?appid=440&count=3

Bạn có thể đọc thêm cụ thể về lệnh gọi này tại đây: ISteamNews/GetNewsForApp

Lấy SteamID của người dùng

API Web Steamworks xác định từng người dùng bằng cách sử dụng ID Steam 64-bit độc nhất của họ. Tham khảo Xác thực người dùng và quyền sở hữu để được hướng dẫn lấy Steam ID của người dùng an toàn.

Địa chỉ host API Web, các cân nhắc về tường lửa

API Web công khai (api.steampowered.com) nằm dưới edge cache của Akamai, vì thế địa chỉ IP thật sự thấy theo tên sẽ khác nhau tùy theo vị trí của bạn và những thay đổi dịch vụ đang diễn ra. IP có thể thay đổi liên tục và linh động, nên nếu lệnh gọi API Web được thực hiện qua tường lửa với yêu cầu gửi đi, hãy đọc tiếp.

Bạn nên dùng node dành riêng cho đối tác (https://partner.steam-api.com) đối với tất cả yêu cầu được thực hiện từ máy chủ bảo mật của mình. Máy chủ này có một số thuộc tính khác với máy chủ công cộng:
  • Chỉ có thể truy cập thông qua HTTPS.
  • Không nằm sau edge cache của Akamai.
  • Mọi yêu cầu đối với host phải được thực hiện bằng mã API Web nhà phát hành, ngay cả những yêu cầu mà bình thường không cần bất kỳ mã nào. Yêu cầu được thực hiện mà không có mã nhà phát hành hợp lệ sẽ trả về mã lỗi 403.
  • Các yêu cầu tạo mã trạng thái 403, thường xảy ra khi dùng mã API Web thông thường hay vì mã nhà phát hành, sẽ dẫn đến giới hạn tốc độ nghiêm ngặt cho IP kết nối. Đây là cách để đảm bảo tính khả dụng cao.
  • Nếu bạn sẽ gửi yêu cầu đến dịch vụ API này từ host có bộ lọc tường lửa áp dụng cho yêu cầu gửi đi, hãy thêm tên DNS 'partner.steam-api.com' vào danh sách cho phép. Nếu tường lửa của bạn chỉ hỗ trợ địa chỉ số, hãy thêm khối CIDR sau vào danh sách cho phép: 208.64.200.0/22.
    LƯU Ý: Không nên kết nối với máy chủ API Web bằng IP; hãy sử dụng tên DNS. Các địa chỉ được chỉ cung cấp cho khách hàng cần đưa chúng vào danh sách trắng trong tường lửa.

Danh sách trắng các địa chỉ IP

Chúng tôi cho phép lập danh sách trắng địa chỉ IP cho các lệnh gọi API Web. Đây là lớp bảo mật bổ sung trong trường hợp mã WebAPI của bạn bị xâm phạm, vì nó đảm bảo chỉ các lệnh gọi WebAPI từ các địa chỉ IP trong danh sách trắng mới thành công. Khi bất kỳ IP nào đã có trong danh sách trắng, tất cả yêu cầu từ địa chỉ không có trong danh sách trắng sẽ bị chặn và trả về phản hồi lỗi 403 - Forbidden.

Dễ dàng để thêm địa chỉ IP vào danh sách trắng. Từ trang nhóm nào có mã WebAPI, nhấp nút "Quản lý mã WebAPI" và làm theo hướng dẫn.

Mỗi mã WebAPI sở hữu whitelist của riêng nó, và không bắt buộc thêm địa chỉ IP vào.

Lưu ý: Whitelist không đồng nghĩa với bảo mật mã WebAPI. Giữ an toàn mã của bạn, không chia sẻ, và thay đổi ngay trong trường hợp bị xâm nhập.