Aikの技術日記

技術的な進捗とか成果とかを細々と投稿するブログです。時々雑記も。

esa.ioのAPIを使用して記事をインポートしてみた

はじめに

お久しぶりです、筆者です。
最近お仕事が大変だったり、Library of Ruinaやcyberpunk2077の影響だったりでブログ記事を更新し切れてませんでしたね…。

久しぶりの今回の投稿では、個人用ドキュメント作成にお世話になってる『esa.io』というサービスのAPIについてまとめていこうかと。
esa.io

せっかくですのでこのesa.ioについても軽く紹介してからまとめていこうかと。
APIのまとめだけでいい場合はこちらから読み始めてください→API概要

それではいきましょう。

※本記事に書かれている内容は「執筆当時(2021/01/07)」段階での情報を元に構成されたものです。
情報が古い可能性もあるので悪しからず。

esa.ioとは

こちらのサービスは「Markdownベースでドキュメント管理ができるサービス」です。
有料ですが月々500円と結構お安めなサービスです。
料金は、そのチーム内(Slackで言うワークスペースみたいなもの)のメンバーが増える毎に+500円加算されていきますが…。
個人用ドキュメント(メンバー数が1人のチーム)であれば気にならないでしょう。

もちろんドキュメント自体を非公開にも公開にもできます。
また、ドキュメント内の「一部のページ」のみ公開にもできるそうです。
※共有用のURLが発行される形で共有できます、くわしくはこちら(公式Docs)

どんな感じで利用できるかは、esa.ioのドキュメントを見るといいかと。
docs.esa.io

esa.ioでは「サービスヘルプドキュメントをesa.io自身で作っている」ので、ドキュメントを見ればどんな感じのツールかも分かるかと。
ただし…もちろんのことながらドキュメントでは編集モードは使えません、閲覧のみ可能です。
もし編集モードも試してみたいときは、1ヶ月のFree Trialで試してみるのも良いかと。

また、esa.ioには「エクスポート」機能と「インポート」機能もあります。
エクスポート機能は画面上から使用できるのですが、インポート機能は現状API経由からしか行えないそうです…。
インポート機能を使うのであれば、esa.ioAPIを使うしか選択肢はないですね…。

というわけで、esa.ioAPIについて見ていきましょう。

API概要

esa.ioAPIでは下記の様なことができる様です:

  • 所属チームの基本情報、統計情報取得(チームに投稿された記事総数も見れます)
  • 所属チームの統計情報取得(直近24時間以内に記事投稿等を行ったメンバー数も見れます)
  • 各記事の情報取得(記事のコメント内容やスター数も取得可能です)
  • 記事の投稿、編集、削除
  • チーム招待用URL発行&再取得
  • カテゴリ情報取得
  • チーム内で使用している絵文字情報取得

ちなみに、esa.ioAPIは利用制限が設けられているらしく…。
「ユーザ毎に15分間毎75リクエストまで」しか叩けません。
※問い合わせれば、チーム毎に「一時的に」利用制限の緩和ができるそうですが…

API発火時点で「あと何回APIが発火できるか」については、レスポンスヘッダの下記のパラメータを参照とのこと。

X-RateLimit-Limit: [リクエスト可能な最大数]
X-RateLimit-Remaining: [現時点で残っているリクエスト可能数]
X-RateLimit-Reset: [リクエスト回数がリセットされる日時(UNIXタイムスタンプ形式)]

ちなみにちなみに、esa.ioAPIHTTPSリクエスト形式のもののみ提供されています。Web APIというものに分類されるかな?
APIは機能別にGET, POST, PUT, PATCH, DELETEのHTTPメソッドを使用してあります。
機能毎にHTTPメソッドをきちんと使い分けているのは好感持てますね…。

GETリクエスト以外のリクエストには文字UTF-8Bodyパラメータを使用し、JSON形式でデータを送付する様に規定されているそうです。
XML形式じゃなくて本当によかった…。

もっと詳しく知りたい場合はesa.ioの公式ドキュメントを参考に。

概要はこんなところで、お次はいよいよesa.ioAPIを触ってみましょう。

APIを使ってみよう-事前準備

esa.ioAPIを使用する…前にまずは事前準備を。

esa.ioAPIを使用するには、事前に「アクセストークンの取得」が必要になります。
アクセストークンの取得方法には大きく分けて2種類あります:

  1. 所属チームの設定画面より直接アクセストークンを使用する方法
    • 👍画面から手軽に発行可能
    • 👎ユーザー毎には発行できない
  2. OAuthを使用し外部アプリケーション使用ユーザー毎に取得する方法
    • 👍ユーザー毎にアクセストークンを発行できる
    • 👎手軽には利用できず使用ハードルが高い

今回は手軽さを優先し、1の「直接アクセストークンを使用する」方法でいこうかと。

APIを使ってみよう-実践編

さてアクセストークンも取得したので…あとは書くだけですね。
ここからの実装方法は流石に省略します。いろんな方法あると思うので…。

参考までに、私の方でNode.jsベースの「記事のインポートを行うスクリプト」を作ってみたので参考までに:
esa-api_sample/import_file.js at main · aik0aaac/esa-api_sample · GitHub

…ただ、ここで終わっても味気ないのでね。
記事のインポートを行うのに使用したAPIが、どんな感じのものかを紹介できればと。

記事インポートにAPI紹介

今回記事インポートに使用したAPIは、esa.ioでは「記事を新たに投稿する」APIとして提供されています。
公式ドキュメント

POST形式のメソッドで、記事を投稿できるAPIです。
最低限必要な情報は「記事タイトルname」だけですね。

必須以外のパラメータについては下記を参照に:

// POST https://api.esa.io/v1/teams/docs/posts HTTP/1.1
// Content-Type: application/json

{
   "post":{
      "name":"[記事タイトル]",
      "body_md":"[記事内容(Markdown形式で記述)]",
      "tags":[
         "[登録したいタグを配列形式で指定可能]",
      ],
      "category":"[記事カテゴリ、`日報/10月`のカテゴリで登録する場合はそのまま`日報/10月`と打てばOK",
      "wip": [WIPモードで投稿するかどうかのBool値。デフォルトではtrue(WIPモードで投稿)],
      "message":"[コメント内容]"
   }
}

レスポンスデータはこんな感じ:
※公式Docsの記述を引用させていただきました

{
  "number": 5,
  "name": "hi!",
  "full_name": "dev/2015/05/10/hi! #api #dev",
  "wip": false,
  "body_md": "# Getting Started\n",
  "body_html": "<h1 id=\"1-0-0\" name=\"1-0-0\">\n<a class=\"anchor\" href=\"#1-0-0\"><i class=\"fa fa-link\"></i><span class=\"hidden\" data-text=\"Getting Started\"> &gt; Getting Started</span></a>Getting Started</h1>\n",
  "created_at": "2015-05-09T12:12:37+09:00",
  "message": "Add Getting Started section",
  "url": "https://docs.esa.io/posts/5",
  "updated_at": "2015-05-09T12:12:37+09:00",
  "tags": [
    "api",
    "dev"
  ],
  "category": "dev/2015/05/10",
  "revision_number": 1,
  "created_by": {
    "myself": true,
    "name": "Atsuo Fukaya",
    "screen_name": "fukayatsu",
    "icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  },
  "updated_by": {
    "myself": true,
    "name": "Atsuo Fukaya",
    "screen_name": "fukayatsu",
    "icon": "http://img.esa.io/uploads/production/users/1/icon/thumb_m_402685a258cf2a33c1d6c13a89adec92.png"
  },
  "kind": "flow",
  "comments_count": 0,
  "tasks_count": 0,
  "done_tasks_count": 0,
  "stargazers_count": 0,
  "watchers_count": 1,
  "star": false,
  "watch": false
}

「記事ID」も返却されるので、作成した記事をそのまま編集したい場合にも活用できそうです。

執筆当時のesa.ioAPI一覧には、「記事インポート」にあたるAPIがなかったため…おそらくこれを使用して記事インポートを行なっていくしかないんじゃないかなぁと思います。
本当は画面上から、フォルダをアップロードすればその中のMarkdownファイルが一気にインポートできる(カテゴリ階層はディレクトリ構造を元に解析)と嬉しいのですが…今後のアップデートに期待ですね。

おわりに

今回の記事では、esa.ioというサービスにてAPIを介し記事をインポートしてみました。
現時点では、APIを介しては1ファイル1ファイル毎にしかインポートできないですが…。
今後複数ファイルをインポートできる口が増えると嬉しいですね。

おまけとして、筆者がおもしろそうだと感じた下記のesa.io APIのサンプルファイルも用意しました。

  • 記事一覧取得
  • 所属チーム基本情報取得
  • 所属チーム統計情報取得
  • 所属チーム参加メンバー情報取得

サンプルファイル:
esa-api_sample/talend-api-tester_export.json at main · aik0aaac/esa-api_sample · GitHub

上記リンクファイルを保存し、Talend API TesterというChrome拡張機能にExportすると使用できると思います。
※「チーム名」と「AccessToken」についてはEnvironmentsに載っけてるので、適宜変更してご使用ください
もしよければ使ってみてください。

それでは|д゚*)

Steam APIについてまとめてみた Part3

はじめに

こんにちは、筆者です。

前回、前々回の記事にて、Steam APIの概要や野良で叩けるSteam Web APIについてまとめていきました。
今回はSteam Web APIには分類されない面白そうなAPI、「レビュー取得API」についてみていきます。
※このAPIも野良で叩けます

それではいきましょう。

レビュー取得APIについて

執筆当時の段階では、レビュー取得APIには大きく分けて下記の2つがある様です:

  1. レビューの内容を取得するAPI
  2. レビューのヒストグラムを取得するAPI

それぞれ詳しく見ていきましょう。

レビュー内容取得API

  • URL[GET] https://store.steampowered.com/appreviews/[appidを入力]?json=1
  • オプションパラメータ:
    • filterstring: 並び順を指定可能、値には下記の値を指定
      • [recent]: 作成日時の降順
      • [updated]: 最終更新日時の降順
      • [all] (デフォルト値): 有用性順(「参考になった」順)、後述するday_rangeパラメータと一緒に使う
    • day_rangestring: 有用性順の日時範囲を指定可能(?)、filter>[all]パラメータと一緒に使う
      • 例えば「参考になった」レビューの中でも「3日前までのものを取得したい」場合はここに3日前と指定する
    • languagestring: レビューの言語を指定
      • 指定可能な値はここの「サポート言語>API言語コード」を参照
      • 言語を指定しない場合は[all]と指定
    • review_typestring:レビューの種類を指定できる, 下記の値を指定
      • [positive]: 肯定的なレビュー
      • [negative]: 否定的なレビュー
      • [all] (デフォルト値): すべて
    • purchase_typestring: レビュー投稿者のアプリ購入経路を指定できる, 下記の値を指定
      • [steam] (デフォルト値): アプリをSteam上で購入したユーザー
      • [non_steam_purchase]: アプリをSteam上で購入しなかったユーザー
      • [all]: すべて
    • num_per_pagestring: レビュー取得最大件数を指定可能(最大100まで)
      • 指定しない場合=20が指定される
    • cursorstring: リクエストのページ指定が可能、詳しくは後述

このAPIは、Steam上の特定アプリの「レビュー」を様々な条件でフィルタリングして表示できます。
レスポンス結果はこんな感じ:

{
  "success": [リクエストの成功フラグ。成功時=1],
  "query_summary": {
    "num_reviews": [取得したレビュー数],
    "review_score": [レビュースコア(数値)],
    "review_score_desc": [レビュースコア説明(「非常に好評」,「圧倒的に好評」などが入る)],
    "total_positive": [肯定的なレビュー総数],
    "total_negative": [否定的なレビュー総数],
    "total_reviews": [クエリパラメータと合致するレビュー総数(全レビューの総数ではない)]
  },
  "reviews": [{
    "recommendationid": [「おすすめ」の固有ID],
    "author": {
      "steamid": [ユーザーのSteamID],
      "num_games_owned": [ユーザーが所有するゲーム数],
      "num_reviews": [ユーザーが投稿したレビュー数],
      "playtime_forever": [ユーザーの対象アプリの通算プレイ時間],
      "playtime_last_two_weeks": [ユーザーの対象アプリの直近2週間のプレイ時間],
      "playtime_at_review": [ユーザーの対象アプリのレビュー記載時点のプレイ時間],
      "last_played": [ユーザーの最終プレイ時間(unixタイムスタンプ)]
    },
    "language": [言語],
    "review": [レビュー内容],
    "timestamp_created": [レビュー作成日(unixタイムスタンプ)],
    "timestamp_updated": [レビュー最終更新日(unixタイムスタンプ)],
    "voted_up": [true=「肯定的なおすすめ」レビューと判定されたレビュー],
    "votes_up": [「参考になった」と評価したユーザー数],
    "votes_funny": [「面白い」と評価したユーザー数],
    "weighted_vote_score": [「参考になった」スコア(単位:%)],
    "comment_count": [このレビューに対するコメント数],
    "steam_purchase": [true=このレビュー作成者がSteamで対象ゲームを購入した],
    "received_for_free": [true=レビュー投稿時に「アプリを無料で入手した」にチェック],
    "written_during_early_access": [true=アーリーアクセス期間中にレビューを投稿した],
    "developer_response": [開発元からのこのレビューへのコメント(無い場合はプロパティごと存在しない)],
    "timestamp_dev_responded": [開発元からのこのレビューへのコメント投稿日時(unixタイムスタンプ)(無い場合はプロパティごと存在しない)]
  }],
  "cursor": [条件に合うレビューが20個より多い場合に付与, 次のリクエストのcursorにこの値をつけることで21個目以降のレビューを取得可能]
}

基本的にはSteamストア上で見れる情報ばかりですが、votes_upvotes_funnyなどデータとして取得できると色々と可能性がありそうなパラメータもありますね。
※参考記事: User Reviews - Get List (Steamworks Documentation)

以下、個別で解説が必要なパラメータについての補足をば…。

オプションパラメータcursorの補足

本パラメータは「全レビューを取得したい」時に使用するものです。

というのも、本APIのレビュー最大取得件数が100件である都合上、条件に合致するレビューが100件以上ある場合、1リクエストで全てのレビューを取得できないため…。
101件目以降のレビューも取得できる様に、本APIでは「100件以上該当レビューがある場合、レスポンスにcursorという値も一緒に返される」様になっています。

そして、次リクエスト時に「レスポンス内のcursor」をパラメータに付与することで、101件目以降のレビューも取得できる様になっています。
次リクエスト(101件目のレビュー~200件目までのレビュー取得)時に、「201件以降も該当レビューがある場合」は再度レスポンスにcursorという値も一緒に返されるので…。
そのまた次のリクエスト時にその値を使うことで、無限にレビューを取得できる、という仕組みです。

ちなみにですが、返却されるcursorの値は「URLEncodedが必要な文字が含まれている」可能性があるそうなので…。
使用する時は、念のためURLEncodedしてから使用した方が良さそうです。

レスポンスパラメータreceived_for_freeの補足

Steamでは「アプリを無料で入手する」方法があり、例えば:

  • Steamフレンドにプレゼントしてもらう
  • 何らかの方法でSteamキー(製品の無料化コード)を入手し、それ経由で入手する

…といった形でアプリを無料で入手できるのです。
ただ、この情報はSteam上には保持されていない(もしかしたら保持されてるかもですが)ためか…。
「上記の方法で入手したプレイヤーのレビュー」と、「お金を支払って入手したプレイヤーのレビュー」は区別して表示されません。

無料で入手したプレイヤーの中でも、例えば「フレンドからのプレゼント」で入手した方などは、下手すると「そのゲームが自分に合わないのにプレイした」場合だってありますよね。
(もちろん普通に購入したユーザーでもその場合になるケースはあるでしょうが)
また、クラウドファンディングに参加した特典ならともかく「自分でお金を出して買ったわけでは無い」プレイヤーと、「お金を支払って入手した」プレイヤーとでは感じる感想が変わるかもしれません。

そういったことへの配慮のためか、Steamのレビューでは「アプリを無料で入手した場合」にチェックを入れられる機能があります。
received_for_freeはこのチェックを入れたかどうかを見れる、というわけですね。

この値をどう処理するかはAPIの利用者次第ですが…工夫すれば面白い結果が得られるかもしれませんね。

ただ、前述の通り「このチェックボックスにチェックを入れるかはレビュー投稿者が任意で選べる」ものです。
チェックボックスにチェック入れ忘れた」とか「故意にチェックを入れなかった」場合は取得できないので、その辺りは注意が必要です。

レビューヒストグラム取得API

こちらは「レビューのヒストグラムデータ」を取得できるAPIです。
ここでいうヒストグラムというのは、Steamストア上にある下記のグラフのことを指します:

"レビューのヒストグラム"
これこれ

ちなみに本APIに関する情報は、公式Docsからは見つかりませんでした…筆者の調査不足かもしれませんが…。
というか、本APIに関してはネットで検索しても下記のQiita記事しかヒットしません:

Steamに登録されている大量のゲームから埋もれている名作を見つけ出す - Qiita

…というわけで、レスポンス結果の値が何を示すのかは「筆者の推測」となっています…ご了承ください。
レスポンス結果はこんな感じ:

{
  "success": [リクエストの成功フラグ。成功時=1],
  "results": {
    "start_date": [集計開始日(unixタイムスタンプ)],
    "end_date": [集計終了日(unixタイムスタンプ)],
    "weeks": [],
    "rollups": [{ヒストグラムデータ
      "date": [対象期間(unixタイムスタンプ)],
      "recommendations_up": [対象期間中の肯定的なレビューの投稿数],
      "recommendations_down": [対象期間中の否定的なレビューの投稿数]
    }
    {...以降同一フォーマットのデータが並ぶ、恐らくヒストグラムグラフの1項目を示すデータ}
    ],
    "rollup_type": [上記`rollups`の対象期間がどんな区切りで示されているかを示す, "week"や"month"などが入る],
    "recent": [{直近のヒストグラムデータ
      "date": [対象期間(unixタイムスタンプ)],
      "recommendations_up": [対象期間中の肯定的なレビューの投稿数],
      "recommendations_down": [対象期間中の否定的なレビューの投稿数]
    }]
  },
  "count_all_reviews": [謎値, truefalseが入る],
  "expand_graph": [謎値, truefalseが入る],
}

参考情報がめちゃくちゃ少なくちょっと謎なAPIですが、レビューの総括が見れる様なAPIなので…。
使いこなせればとても優秀そうなAPIですね。

以上で「野良で叩けるSteam API」は以上になります。
ここからは筆者のちょっとした感想を述べていければ。
(必要ないならおわりにまで読み飛ばしてください)

総括

ここまで「野良で叩けるSteam API」を見てきましたが、基本的にはデータを取得するだけAPIしか叩けないなという印象です。
いやそりゃそうなんですけどね…野良でデータの書き換えが出来てしまうのはセキュリティ的にまずいと思うので。

野良では叩けないAPIには、データ操作が可能なAPIもゴロゴロあります。
もちろんその中でも、「開発元が特別に発効しないといけないKey」が必要なAPIもあるので…。
本気でこなし尽くしたいのであれば、開発元と協力関係となりKeyを入手するか…。
自分で作ったゲームをSteamにあげ、それで試すかのどっちかとなると思います。

ただ、野良から叩ける範囲でもこれだけ面白そうな情報が取れるのは非常に興味深いです。
(Twitter APIは過去に散々悪用されてから、API使用が厳しくなった経緯がありますが…Steam APIについてはまだそういった悪用事例が少ないのかなぁと邪推してみたり。)

特にレビュー取得APIについては、実に様々な情報が得られるので活用しがいがありそうです。
他にも「アクティブユーザー数を取得するAPI」も楽しそうですね。
そのゲームコミュニティの活性度が伺えそうです!

おわりに

今回の記事では、Part1, 2に続き野良で叩けるSteam APIを見ていきました。
今回でこれらAPIについては紹介尽くしたので、本シリーズは今記事で終了です。

本当は1記事にまとめようと思ったのですが…。
執筆途中に文字数が10000文字を超え出したあたりで「これやべぇ」と思い、分割しちゃいました。
流石に分割しすぎかな〜と思いましたが、分割した方が不思議と投稿モチベも上がるので良かったのかなぁと。

今後はまとめ上げたAPIを使って、何か面白いツールでも作ってみようかなと思います(時間があれば)。
特に、Part1で話したLibrary of Ruinaについては大好きなゲームということもあり、色々調べたいですね…。
(あとコミュニティが何故か荒れに荒れまくって、開発元のメンタルがやばそうなので…
「いつから荒れだしたのか」「肯定的な意見はあるか」とかを調べて、開発元のメンタルの支えとなる情報を提供できたらいいなと思いつつ…)

最後に1つ余談を。
APIまで使いたくはないけど、Steamのいろんなデータを見たい!」という方に必見なのが、「Steam統計」というものです。

Steamでの「現在最もプレイヤー数が多いゲーム」や、「Steamユーザーの使用PC比率」など面白いデータがたくさん見れる場所となっております…!
アクセス方法については、下記の記事に詳しく書かれていたので参考に。

www.beginner-steamer.com

それでは|д゚*)

SteamAPIについてまとめてみた Part2

はじめに

こんにちは、筆者です。

前回の記事にて、Steam APIの概要や、野良で叩けるSteam Web APIの一部についてまとめてみました。
今回は前回に引き続き、下記のSteam Web APIについてまとめていきます:

  • ISteamRemoteStorage: Steamコミュニティへ投稿されたコンテンツの情報を取得できるAPI
  • ISteamUserStats: Steam登録ユーザーの情報を取得できる
  • ISteamWebAPIUtil: Steamworks Web APIサーバー自身の情報を取得できる

それではいきましょう。

ISteamRemoteStorage

Steamコミュニティへ投稿されたコンテンツの情報を取得できるAPIです。

GetPublishedFileDetails: コミュニティへ投稿されたコンテンツ情報を取得

こちらはコミュニティに投稿された様々な情報を取得可能です。
具体的には、下記のフォーマットのURLで遷移可能なコンテンツの情報を取得できます。
https://steamcommunity.com/sharedfiles/filedetails/?id=[コンテンツの固有ID]

このAPIからは下記のコンテンツを取得可能です:
(筆者が確認した感じこれらのコンテンツは取得できました。他にも取得できるものはあるかもしれません)

実はこれらのコンテンツのURLには、どれもsharedfilesというものがくっ付いております。
Steamシステム上では、これらコンテンツはどれもsharedfilesというカテゴリに属するのでしょう。

もし今後Steamで新しいカテゴリが出来たとして、そのコンテンツのURLにsharedfilesがくっ付いていたら恐らくこのAPIでデータを取得可能かと。

ちなみに、本APIでは「コンテンツのタイトル」や「コンテンツへのURL」「サムネイルデータ」などの概要を示すデータしか取れません。
例えば「ワークショップアイテム」の「MODデータ本体」や、「ガイド」の「本文」情報が取れるわけではないので悪しからず。

※「全てのコンテンツが共通で持っているデータ」を取得できる、というイメージを持つと分かりやすいかも。
「ワークショップアイテム」の「MODデータ本体」や、「ガイド」の「本文」情報はそのコンテンツグループ固有の情報ですしね。

また、本APIはPOSTリクエストのものですので…。
これまでの様に、ブラウザのURLを直叩きしてデータ取得するのはできません。

リクエストを投げたいときは、Terminalより下記の様なコマンドを投げると取れますので参考に。
publishedfileidsが指す値を任意のものに変更してご利用ください。
※なお下記のリクエストで取れるデータは私が作成したMODになってます、悪しからず。

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "itemcount=2" \
   -d "publishedfileids[0]=2224118463" \
   -d "publishedfileids[1]=2203211070" \
 'https://api.steampowered.com/ISteamRemoteStorage/GetPublishedFileDetails/v1/?format=json'

リクエストパラメータの注意点として、itemcountの値はpublishedfileidsの配列長と同じにした方がいいと思います。
というのも、itemcountの値がpublishedfileidsの配列長より少ない数値だと、指定したIDのコンテンツを取得できないのでね…。
(なんでこのパラメータが必須パラメータなのか謎です…。)

レスポンス結果はこんな感じです。
※「スクリーンショット」や「動画」など、異なるカテゴリの投稿であっても返却値は同一です。
※公式Docsに説明がないこともあり、よくわからない返却値が多々ありました…ご了承をば。

{
  "response": {
    "result": [取得件数],
    "resultcount": [取得件数],
    "publishedfiledetails": [
      {
        "publishedfileid": [取得したコンテンツのID],
        "result": [謎値, 1が格納されるのを確認済み],
        "creator": [作成者のSteamId ※数値で返却],
        "creator_app_id": [作成対象のアプリ ※appidと同一値],
        "consumer_app_id": [謎値, ※appidと同一値],
        "filename": [スクリーンショット、画像、ガイドであれば画像ファイル名が格納],
        "file_size": [画像ファイルのサイズ ※数値で返却],
        "file_url": [画像ファイルのURLリンク],
        "hcontent_file": [謎値, 数値で返却],
        "preview_url": [プレビュー画像のURLリンク ※動画は空文字が格納],
        "hcontent_preview": [謎値, 数値で返却],
        "title": [コンテンツのタイトル],
        "description": [コンテンツの説明欄],
        "time_created": [コンテンツ作成日(unixタイムスタンプ形式)],
        "time_updated": [コンテンツ更新日(unixタイムスタンプ形式)],
        "visibility": [謎値, 0が格納されるのを確認済み],
        "banned": [(恐らく)BANされているかどうか, 0=BANされていない?],,
        "ban_reason": [(恐らく)BANされた理由],
        "subscriptions": [サブスクライブ数, ワークショップアイテム以外には0が格納],
        "favorited": [お気に入り数],
        "lifetime_subscriptions": [謎値, サブスクライブ数と関連性ありそう],
        "lifetime_favorited": [謎値, お気に入り数と関連性ありそう],
        "views": [ユニーク訪問者数],
        "tags": [{ "tag": [タグ情報] }]
      }
    ]
  }
}

なお、コンテンツのカテゴリによっては「値が入ってなかったり」しますので御留意を。

APIだけでだいぶ長くなっちゃいましたね…。

説明の締めに、最後に本APIの参考文献を乗っけておきます。
公式Docsに参考情報がほとんどなく…下記のGithub Issueは大変参考になりました!
この場を借りてお礼をば…。

github.com

GetCollectionDetails: コミュニティへ投稿されたコンテンツ情報を取得(簡易版)

こちらもGetPublishedFileDetailsと同様、コミュニティへのコンテンツ情報を取得できるAPIです。
ただ、GetPublishedFileDetailsよりも取得できる情報は遥かに少ないです…。

また、本APIGetPublishedFileDetailsに続きPOSTリクエストのものですので…。
リクエストを投げたいときは、下記のコマンドを参考に。
publishedfileidsが指す値を任意のものに変更してご利用ください。
※なおこちらも取れるデータは私が作成したMODになってます、悪しからず。

curl -i -X POST \
   -H "Content-Type:application/x-www-form-urlencoded" \
   -d "collectioncount=2" \
   -d "publishedfileids[0]=2224118463" \
   -d "publishedfileids[1]=2203211070" \
 'https://api.steampowered.com/ISteamRemoteStorage/GetCollectionDetails/v1/?format=json'

レスポンス結果はこんな感じ:

{
  "response": {
    "result": [謎値, 1が格納されるのを確認済み],
    "resultcount": [取得件数],
    "collectiondetails": [{
      "publishedfileid": [取得したコンテンツID],
      "result": [謎値, 9が格納されるのを確認済み]
    }]
  }
}

…正直resultが示す値がなんなのかわからないと、使う意味がない気もしますね…。
また、私は確認できなかったのですがcollectiondetailschildrenという属性値がつくものもあるらしいです。
詳しくはこちらを: garrys mod - Steam Web API GetCollectionDetails not working - Stack Overflow

なお、GetPublishedFileDetailsと同様、リクエストパラメータの注意点として…。
collectioncountの値はpublishedfileidsの配列長と同じにした方がいいと思います。
(これもなんでこのパラメータが必須パラメータなのか謎ですね…。)

ISteamUserStats

ユーザーの情報へのアクセスに使用します。

GetGlobalAchievementPercentagesForApp: 実績取得比率を取得

これは指定されたアプリの「実績取得比率」を取得できるものです。結構面白いAPIですね。

…まぁ同一の情報はSteamから見れるんですけどね。
https://steamcommunity.com/stats/[appid]/achievementsのURLに飛んだら見ることができます。

レスポンス結果はこんな感じ:

{
  "achievementpercentages": {
    "achievements": [
      { "name": [実績名], "percent": [実績を獲得したユーザー/そのゲームをプレイした全ユーザー] }
    ]
  }
}

実績名には恐らく裏側での管理IDが入っており、PUBGでこのAPIを叩くと実績名にはACHIVE018といった簡素な名前が入ってました。
まぁ多言語対応の都合上、実績名に「Steam上で表示している名前」を入れるわけにもいかないでしょうしね…妥当な判断です。

ちなみに管理IDがどれを指すのかは、Steamdbを見てみるとわかります。
https://steamdb.info/app/[appid]/stats/で分かりますので、ここと照らし合わせながら見る感じになるかなと。

ちなみに、Library of Ruinaの様な「実績が設定されてない」アプリだと空データが返ってきます。

GetGlobalStatsForGame: グローバル統計データを取得

  • URL[GET] https://api.steampowered.com/ISteamUserStats/GetGlobalStatsForGame/v1/
  • 必須パラメータ:
    • appid[uint32]: 情報を取得したいアプリID。※後述するグローバル統計が有効になっているアプリのみ可
    • count[uint32]: データを取得する統計数
    • name[0][string]: データを取得する統計名
  • オプションパラメータ:
    • startdate[uint32]: データの測定開始日を指定(unixタイムスタンプ)
    • enddate[uint32]: データの測定開始日を指定(unixタイムスタンプ)

先に申し上げますと、このAPIはエンドユーザー向けのAPIではないかなと思います。
このAPIを本当に活用したいのであれば、非常に労力がかかる作業が要求されるかと思います…あらかじめご認識をば。

このAPIの説明をするには、Steamworksの概念の1つ「統計データ」の知識が必要ですので…軽く説明をば。
※公式Docsに書いている知識を噛み砕いて記したものです。詳細は公式Docsを参照に。

「統計データ」というのは、Steamアプリをプレイするユーザーの「プレイ時間」や「プレイ中の死亡回数」など、細やかな情報が登録できるものです。
その細やかさから、「ゲームの内部データの追跡」にも使用することが可能です。

これを使うことで例えば、「複数台のコンピュータを使用する1人のユーザの、すべてのセッションにわたるゲームプレイのデータを収集して、実績を付与する」といったこともできます。
どちらかというと「ゲームを開発する」側が参考にする情報、といった感じでしょうか。

ちなみに統計データを取得するにはそれなりに設定しなければならない事がありそうです…。
統計データを取得するには「統計名」や「統計データの型」「どういった時にその統計データが更新されるか」などなど実に様々なことを設定する必要があるそうで…。
詳細は公式Docsを参照に。

そして、本APIは「グローバル統計データ」という「各ユーザーごとの情報」ではなく「全ユーザーを統合して見た」情報を取得できるAPI…の一部です。
このAPIと、野良では叩けないAPIを駆使すれば、例えば「そのゲームの全ユーザーのプレイ時間総数」や「全ユーザーの合計死亡数」といった情報を集計することも可能…っぽいです。

ただし、これらの情報を得るには事前に「そのアプリにどんな統計データが登録されているのか」を知る必要があります。
(GETパラメータ内部のname[0]の値を指定するためですね)

こちらの情報については、Steamdbに載ってはいそうなのですが…。
https://steamdb.info/app/[appid]/stats/から閲覧可能です

よしんばその統計データ名がわかったとしても、「それがグローバル統計データに対応しているかどうか」は別問題である様です。
これがこのAPIを野良で叩きにくくしている原因です。

もし対象の統計データ名がグローバル統計非対応のものだと、下記の様なレスポンスが返ってきます…:

{
  "response": {
    "result": 8,
    "error": "Stat 'total_wins' is not an aggregated stat"
  }
}

もしそのアプリ開発者ではない、エンドユーザーからAPIを叩こうとしたら「Steamdb上に掲載されている統計データ名を」「かたっぱしから叩いてみて」「データが取れたらラッキー」 …的な感じになるかと…。

そんなわけで、本APIのレスポンス形式は調査できませんでした…。
一応Web上に参考情報となり得る記事がありましたので、その記事のURLだけ貼っておきます:
WebAPI/GetGlobalStatsForGame - Official TF2 Wiki | Official Team Fortress Wiki

GetNumberOfCurrentPlayers: アクティブプレイヤー数を表示

こちらは指定したアプリの「現時点でのプレイ人数」を取得するものです。
ただし、Steamに接続していない状態でプレイしている人はカウントされません。
(Steam側で検知できないからですね)

オフラインで完結できちゃうゲームについては、あまり当てにならない値が返ってくるかもですね。
逆にオンライン対戦が前提のゲームであれば、かなり信頼ある値が取れそうです。

レスポンス結果はこんな感じ:

{
  "response": {
    "player_count": [現時点でのプレイ人数],
    "result": [謎値, 1が格納されることを確認済み]
  }
}

ISteamWebAPIUtil

このAPIカテゴリでは、「Steamworks Web API」そのものに関する情報を取得できます。
現時点でサポートされているAPIのリストも返してくれる様ですが、野良では叩けません…。

代わりに野良では下記のAPIが叩けます。

GetServerInfo: APIサーバーの情報取得

「Steamworks Web API」が稼働しているサーバー情報を取得できます。
レスポンス結果はこんな感じ:

{
  "servertime": [サーバーの現在時刻(unixtimeスタンプ)],
  "servertimestring": [サーバーの現在時刻(文字列)]
}

servertimestringは叩いてみたら、日本時間よりも「-16時間」されていました。
アメリカの西あたりで稼働しているサーバーってことになりますね。

ただ、AWSなどのクラウドサービスを使っていたり、APIサーバーを国単位で分散化していたら全く違う結果が返ってくるかと。
Steamは巨大なプラットフォームですから、流石に分散されているでしょうしね…。

おわりに

今回は、Part1に紹介しそびれてた「野良で叩けるSteam Web API」について見ていきました。

今回で野良で叩けるSteam Web APIは紹介し尽くしましたが…。
Steam Web APIとは別に面白そうなAPIがあるので、次回Partではそちらについて見ていきましょう。

それでは|д゚*)