メインコンテンツへスキップ

はじめに

Square Cloud で Telegram ボット を開発してホストするには、構成と前提条件の体系的な手順に従うことが不可欠です。この技術ガイドでは、初期セットアップから本番環境へのデプロイまで、プロセス全体を解説します。

前提条件

  • Square Cloud アカウント: 登録ページからメールアドレスを使って登録します。
  • 有効なプラン: アプリケーションに専用リソースと最適化されたパフォーマンスを提供します。利用可能なプランを確認し、ニーズに最も適したものを選択してください。
このガイドは Node.js ランタイムまたは Python ランタイムで動作します。

プロジェクトの作成

Telegram アカウントは、ボットのテストと操作に不可欠です。まだお持ちでない場合は、Telegram 公式サイト にアクセスしてアカウントを作成してください。

Telegram でのボットアプリケーション

BotFather を見つける

Telegram Web にアクセスし、プラットフォーム上でボットの作成と管理を担当する公式の BotFather ボットを検索します。
Telegram で BotFather を見つける

トークンを取得する

BotFather との会話を開始し、/start と入力します。次に、/newbot オプションを選択して新しいボットを作成します。システムがボットの名前を尋ね、確認後、必要な認証トークンが自動的に生成されます。
BotFather で Telegram ボットのトークンを生成する
トークンは秘密に: このトークンはボットの完全な制御権を与えます。コードに書いたり ZIP に入れたりしないでください。以下の例では、環境変数 TELEGRAM_BOT_TOKEN から読み込みます。

ボットの開発

grammY (Node.js) または pyTelegramBotAPI (Python) でボットを書きます。どちらの例も、すべてのテキストメッセージをそのまま返します。
  1. システムに Node.js がインストールされていることを確認してください。まだの場合は、Node.js 公式サイト からダウンロードしてください。
  2. 新しい Node.js プロジェクトを初期化します。
Terminal
  1. grammY ライブラリをインストールします。
Terminal
  1. 次の構造でメインファイル (index.js) を作成します。
index.js

Square Cloud の設定

プロジェクトのルートに、メインファイルと並べて squarecloud.app ファイルを作成します。このファイルは、ボットの実行方法を Square Cloud に伝えます。
  • MAIN は Square Cloud が実行するファイル、MEMORY はボットの RAM (MB) です。ボットには最低 256 MB が必要で、512 MB あれば成長の余地があります。
  • AUTORESTART=true を指定すると、ボットがクラッシュしたときに再起動します。自動再起動の仕組みを参照してください。
  • SUBDOMAIN はありません。ロングポーリングでは、ボットに公開 URL は必要ありません。
すべてのフィールドについては設定ファイルのリファレンスを参照してください。

ボットトークンの設定

コードはトークンを環境変数 TELEGRAM_BOT_TOKEN から読み込むため、トークンがファイルに入ることはありません。次のいずれかの方法で設定します。
  • ダッシュボード: アップロードページで 詳細設定 を開き、TELEGRAM_BOT_TOKEN という名前の変数を追加して、値にトークンを入力します。すでにデプロイ済みのボットの場合は、アプリケーションの 環境変数 ページで追加し、ボットを再起動します。
  • CLI: ボットをアップロードした直後に (デプロイと動作確認を参照)、squarecloud app env set で設定し、ボットを再起動します。
ボットは起動時に環境変数を読み込むため、変更のたびに再起動してください。その他の管理方法については環境変数を参照してください。
先に手元のコンピューターでボットを実行するには、ターミナルで変数を設定します。macOS と Linux では export TELEGRAM_BOT_TOKEN=your_token_here、PowerShell では $env:TELEGRAM_BOT_TOKEN="your_token_here" です。

ZIP に含めるもの

  • メインファイル (index.js または main.py) と、その他のソースファイル。
  • package.json または requirements.txt。
  • squarecloud.app。
node_modules、.venv、__pycache__ は含めないでください。依存関係はボットの起動時に Square Cloud がインストールします。

デプロイと動作確認

上で説明した ZIP を作成し、アップロードします。

ダッシュボード経由

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 を開き、アプリケーションが応答することを確認してください。ボットをデプロイした場合は、コマンドを送信してオンラインになっていることを確認してください。
アプリが起動しませんか?よくある原因と修正方法はトラブルシューティングガイドを参照してください。

ボットのテスト

デプロイ後、Telegram でボットを見つけてメッセージを送信します。ボットが同じテキストを返信すれば、動作していることが確認できます。
デプロイ後に Telegram ボットをテストする

よくあるエラー

Error 409: Conflict: terminated by other getUpdates request

同じトークンで別のボットのコピーが更新を読み取っています。たとえば、手元のコンピューターで起動したものです。Telegram は、1 つのボットにつき 1 つのロングポーリング接続にしか更新を届けません。もう一方のコピーを停止するか、どこで動いているかわからない場合は BotFather でトークンを無効化してから、新しいトークンを設定してボットを再起動してください。

Error 401: Unauthorized

トークンが間違っているか、無効化されています。BotFather から現在のトークンをコピーして設定し直し、ボットを再起動してください。

空のトークンまたは KeyError: 'TELEGRAM_BOT_TOKEN'

変数 TELEGRAM_BOT_TOKEN が設定されていません。grammY は Empty token! で停止し、Python の例は KeyError で停止します。ボットトークンの設定のとおり変数を設定し、ボットを再起動してください。

次のステップ

アプリが起動しない

モジュールの不足、メモリエラーなどの起動エラーを修正します。

環境変数

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

python-telegram-bot と aiohttp

python-telegram-bot を使っていますか?頻発する NetworkError 例外を修正します。
これらのライブラリの詳細は、grammY 公式ドキュメントと PyPI の pyTelegramBotAPI ページを参照してください。

お問い合わせ

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