Skip to main content

はじめに

  • このガイドは、top.gg で承認済みの Bot があり、プロジェクトに Node.js または Python を使用していることを前提としています。
  • 次に、Square Cloud のアカウントを作成する必要があります。これは サインアップページ から行えます。メールアドレスを使ってアカウントを作成できます。
  • 最後に、アカウントに有効なプランが必要です。利用可能なプランを比較し、ニーズに合ったものを選んでください。

環境のセットアップ

  1. はじめる前に、システムに Node.js と npm がインストールされていることを確認してください。まだお持ちでない場合は、Node.js 公式サイト からダウンロードできます。
  2. 次のコマンドで新しい Node.js プロジェクトを開始し、import 構文を有効にします。
Terminal
これらのコマンドは、現在のディレクトリに package.json ファイルを作成します。
  1. Express をインストールします。
Terminal

プロジェクトのセットアップ

1. Webhook シークレットを取得する:
  • Square Cloud でアプリケーションが使用するサブドメイン (設定ファイルの SUBDOMAIN フィールド) を決めます。たとえば mysite の場合、Webhook URL は https://mysite.squareweb.app/topgg になります。
  • Top.gg でプロジェクトのダッシュボードを開き、Webhooks に移動します。
  • Webhook URL を貼り付けて保存します。すると Top.gg が whs_ で始まる Webhook シークレットを生成するので、コピーして他人に知られないように保管してください。コードはこれを環境変数 TOPGG_WEBHOOK_SECRET から読み取ります。
Top.gg はすべてのリクエストに x-topgg-signature ヘッダーで署名します。形式は t=<timestamp>,v1=<signature> で、signature はシークレットを使って <timestamp>.<raw body> から計算した HMAC SHA-256 です。以下のコードはこれを再計算し、一致しないリクエストをすべて拒否するため、第三者があなたの URL に偽の投票を送ることはできません。詳しくは Top.gg の Webhook ドキュメントを参照してください。
このガイドでは Top.gg の v1 Webhook を使用します。Authorization ヘッダーでパスワードを送り、ペイロードも異なる従来の v0 Webhook は、ここでは扱いません。
2. Webhook リスナーを実装する: 以下のセクションでは、JavaScript と Python の両方のコード例を示します。
この例では Node の組み込み crypto モジュールで署名を検証するため、Top.gg のパッケージは不要です。@top-gg/sdk 4.0.0 の Webhook クラスは使用していません。私たちのテストでは、そのリスナーが正しい配信にタイムアウトエラーで応答し、Top.gg に再送させてしまったためです。
index.js

squarecloud 設定ファイルの作成

プロジェクトフォルダーに squarecloud.app ファイルを作成します。SUBDOMAIN にはステップ 1 で決めたサブドメインを設定します。
SUBDOMAIN はリスナーを https://mysite.squareweb.app で公開します。ウェブアプリケーションには少なくとも MEMORY=512 が必要です。コードは、Square Cloud が 80 に設定する環境変数 PORT のポートと、ホスト 0.0.0.0 でリッスンします。

詳しく学ぶ: Square Cloud の設定ファイルの作り方。

squarecloud.app ファイルは、アプリケーションを設定するために使用される設定ファイルです。名前、説明、バージョン、メインファイルなどを定義するために使用されます。

Square Cloud へのアプリケーションのアップロード

すべての手順を終えると、プロジェクトフォルダーにはコード、依存関係ファイル (package.json または requirements.txt)、設定ファイルが揃っているはずです。ダッシュボードからアップロードする場合は、これらを .zip ファイルにまとめてください。 アプリケーションが Node.js プロジェクトの場合は、Node.js に関する記事をご覧ください。 アプリケーションが Python プロジェクトの場合は、Python に関する記事をご覧ください。

ダッシュボード経由

1

アップロードページにアクセス

アップロードページにアクセスし、プロジェクトの zip ファイルをアップロードします。
2

環境を設定

zip をアップロードした後、プロジェクトの名前、メインファイルまたはランタイム環境、その他の設定を構成する必要があります。
ウェブプロジェクトをアップロードする場合は、必ず「Web Publication」を選択し、プロジェクトにサブドメインを設定してください。
3

プロジェクトをデプロイ

最後に「Deploy」ボタンをクリックして、プロジェクトを Square Cloud にホストします。
デプロイ後、ダッシュボードからプロジェクトのステータスとログを監視できます。
Square Cloud へのアプリケーションのアップロード
4

アプリが稼働していることを確認

最初のデプロイは、通常 1 分もかからずに完了します。ダッシュボードでアプリケーションのステータスが running になるのを待ち、起動時のエラーがないかログを確認してください。
ウェブサイトや API をデプロイした場合は、ブラウザで https://<your-subdomain>.squareweb.app を開き、アプリケーションが応答することを確認してください。ボットをデプロイした場合は、コマンドを送信してオンラインになっていることを確認してください。
アプリが起動しませんか?よくある原因と修正方法はトラブルシューティングガイドを参照してください。

CLI 経由

この方法を使用するには、プロジェクトのルートに squarecloud.app という名前の設定ファイルが必要です。このファイルは、アプリケーションの実行方法を Square Cloud に伝えます。

設定ファイルガイド

アプリケーションの環境を定義する squarecloud.app 設定ファイルの作成方法を学びます。
1

CLI をインストール

Square Cloud CLI をインストールします。すでにお持ちの場合は、同じコマンドを実行すると更新されます:
2

ログイン

次のコマンドを実行します。ブラウザが開くので、そこでログインを承認すれば CLI の準備は完了です。API キーをコピーする必要はありません。スクリプトや CI については、CLI の認証を参照してください。
3

プロジェクトをアップロード

プロジェクトのフォルダで次のコマンドを実行します。CLI は squarecloud.ignore に記載されたものを除いて現在のフォルダを zip にし、アップロードします:
自分で作成した zip をアップロードするには、--file で指定します:
4

アプリが稼働していることを確認

最初のデプロイは、通常 1 分もかからずに完了します。ターミナルから直接、アプリケーションのステータスとログを確認してください。
ウェブサイトや API をデプロイした場合は、ブラウザで https://<your-subdomain>.squareweb.app を開き、アプリケーションが応答することを確認してください。ボットをデプロイした場合は、コマンドを送信してオンラインになっていることを確認してください。
アプリが起動しませんか?よくある原因と修正方法はトラブルシューティングガイドを参照してください。

Webhook シークレットの設定

whs_ シークレットを、次のいずれかの方法でアプリケーションの環境変数 TOPGG_WEBHOOK_SECRET として追加します。
  • ダッシュボード: アップロードページで Advanced configuration を開き、デプロイ前に変数を追加します。すでにデプロイ済みのアプリケーションの場合は、その Environment Variables ページで追加します。
  • CLI: プロジェクトフォルダーから squarecloud app env set で設定し、アプリケーションを再起動します。
アプリケーションは起動時に環境変数を読み込むため、変更のたびに再起動してください。シークレットが設定されるまで、コードはすべてのリクエストを 401 Unauthorized で拒否します。その他の管理方法については環境変数を参照してください。

テストの開始

すべて正しく行えていれば、ブラウザで https://mysite.squareweb.app/topgg を開いてください (mysite は自分のサブドメインに置き換えます)。「Cannot GET /topgg」(Node.js) または「Method Not Allowed」(Python) と表示されれば問題ありません。このルートは Top.gg が送る POST リクエストだけを受け付けます。
  • app.post("/topgg", ...) で作成した JavaScript コードの場合、投票を受け取るルートは「/topgg」です。したがって、Web サイトが mysite.squareweb.app であれば、Webhook URL は https://mysite.squareweb.app/topgg です。
  • @app.route("/topgg", methods=["POST"]) で作成した Python コードの場合も、投票を受け取るルートは「/topgg」です。したがって、Webhook URL も同じく https://mysite.squareweb.app/topgg になります。
最後に、Top.gg でプロジェクトの Webhooks ページに戻り、「Send Test」ボタンをクリックします。その後、アプリケーションのログを確認してください。すべてうまくいけば、console.log または print で定義したメッセージがログに表示されるはずです。
Top.gg webhook 送信テストの例
これで、すべて正しく設定されていれば、Bot が top.gg で投票を受け取ったときに通知を送信する webhook の準備が整います。

トラブルシューティング

カスタムドメイン

デフォルトの URL mysite.squareweb.app の代わりにカスタムドメイン(例: mysite.com)を使用するには、Standard プラン以上が必要です。デフォルトの URL は設定ファイルの SUBDOMAIN フィールドから決まります。独自ドメインを接続するには、独自ドメインの設定方法に従ってください。

最小 RAM 要件

ウェブサイトと API は最小 512MB RAMです。これは静的ランタイムで静的ビルドを配信するには十分な量です。サーバー上でページをレンダリングするアプリ(Next.js、Nuxt、Angular SSR など)には、最低 1GB RAMを推奨します。より大規模なアプリケーションでは、メモリ不足でアプリケーションがクラッシュするのを防ぐため、より多くの RAM を割り当ててください。

このサイトが見つかりませんでした。

サブドメイン/ドメインが SUBDOMAIN フィールドまたはカスタムドメイン設定で構成されている内容と一致しているか確認してください。サイトをアップロードしたばかりの場合は、Square が初回アクセスを有効化するまで最大 60 秒お待ちください。

サイトの応答に時間がかかりすぎました…

サーバーはポート 80 とホスト 0.0.0.0 でリッスンする必要があります。Square Cloud はアプリケーションに環境変数 PORT(80)と HOST(0.0.0.0)を設定します。別の値をハードコーディングせず、コードでこれらを読み込んでください。localhost や 127.0.0.1 だけでリッスンしているサーバーには、リクエストが届きません。

次のステップ

Discord ボット

投票を受け取るボットをホストします。

環境変数

Webhook シークレットやその他のシークレットを管理します。

アプリが起動しない

ポートの競合、モジュールの不足などの起動エラーを修正します。

お問い合わせ

技術的な問題が解決しない場合は、専門のサポートチームがお手伝いします。お問い合わせいただければ、どのような問題でも喜んで解決をサポートいたします。サポートの質の高さも、開発者が Google と Trustpilot で Square Cloud に402 件のレビューで 4.9/5という評価をつけている理由の 1 つです。