WeChatAPIを使う準備

2022年3月1日 19:54

WeChatエコシステムには豊富なAPIが用意されています。これらAPIを外部のサーバなどから使う際には事前の準備が必要です。

アクセストークン

WeChatエコシステムのAPIを外部から利用する際に必ず必要になるのがアクセストークンです。例えば公式アカウントのメニューをAPIを使って設定する場合は以下のAPIを利用します。

https://api.weixin.qq.com/cgi-bin/menu/create?access_token=ACCESS_TOKEN

このURLの「ACCESS_TOKEN」の部分にアクセストークンを埋めてリクエストする事で公式アカウントのメニューを設定する事が出来ます。ちなみにメニューの内容はJSON形式でPOSTします。詳しくはドキュメントをご覧ください。
（https://developers.weixin.qq.com/doc/offiaccount/Custom_Menus/Creating_Custom-Defined_Menu.html）

このアクセストークンを取得する方法は2通りありますが、今回はお手軽なオフィシャルアカウントプラットフォームで自分が所有しているアカウントのアクセストークンを取得する方法を説明します。
（もう1つの「オープンプラットフォームのサードパーティ授権機能を使う方法」は今後機会があれば紹介します）

AppIDとAppSecretを確認する

オフィシャルアカウントプラットフォームにログインして公式アカウント、あるいはミニプログラムアカウントのAppIDとAppSecretを確認します。
公式アカウントの場合はログイン後に左のメニューにある「基本配置」をクリックするとAppIDを表示する事が出来ます。AppSecretはAppIDの下にある「启用」をクリックすると発行されます。AppSecretの発行には公式アカウント管理者によるQRコードスキャンが必要です。また、発行されたAppSecretはその場で画面に表示されますが、以後二度と表示する事は出来ません。（公式アカウント管理者であっても表示出来ません）
従って、表示されたAppSecretは必ず自分でテキストファイルなどに保存しておく必要があります。

なお、AppSecretの部分が「启用」ではなく、「重置」になっている場合は注意が必要です。過去にこの公式アカウントにおいてAppSecretが発行されていると、リンクが「重置」になります。（再設定するという意味です）
AppSecretの再設定自体は発行と同じく公式アカウントの管理者によるスキャンがあれば実行可能ですが、再発行した瞬間に以前発行されたAppSecretは無効となります。もし過去に発行したAppSecretがどこかに保存されているのであれば、再発行せずにそのAppSecretを使う事をお勧めします。
やむを得ず再発行するのであれば、過去に誰がどんな目的でAppSecretを発行したのかを良く確認しましょう。
サードパーティの公式アカウント管理ツールなどを利用している場合、古いタイプのものだとAppSecretを使っている可能性があります。そういった場合にAppSecretを再発行してしまうと、そのツールが使えなくなるので気を付けましょう。
ちなみにミニプログラムアカウントの場合はログイン後に左のメニューにある「开发管理」をクリックし、右側に表示されるタブにある「开发设置」をクリックするとAppIDの確認とAppSecretの発行（再発行）が出来ます。
ミニプログラムアカウントの場合も公式アカウントと同様にリンクが「重置」になっている可能性がありますので、十分に注意しましょう。

ミニプログラムのAppID確認とAppSecretの発行
（この例では「重置」になっています）

ホワイトリストを設定する

WeChatのAPIのうち、アクセストークンを使ってアクセスするAPIはアクセストークンさえあればどこからでも利用できますが、公式アカウントのアクセストークンを取得するAPIだけは事前に登録したIPアドレスからしか利用出来ません。ちなみにミニプログラムアカウントのアクセストークン取得APIはデフォルトではどこからでも利用出来ます。（ホワイトリストのIPアドレスだけに限定する事も出来ます）
公式アカウントのホワイトリストはオフィシャルアカウントプラットフォームの管理画面で設定します。ログイン後に「安全中心」をクリックし「IP白名单」の項目にある「去设置」をクリックします。

IPアドレスを入力するボックスが出て来るのでアクセストークン取得APIを実行するサーバのIPアドレスを入力します。IPアドレスを複数設定したい場合は改行して1行に1アドレス記入します。

「确认修改」をクリックすると公式アカウント管理者がスキャンするQRコードが表示されます。

管理者のWeChatでこのQRコードをスキャンすると、スマホ上に最終確認画面が表示されますので、「确定」をタップすれば設定完了です。

なお、ホワイトリストに設定されていないIPアドレスからアクセストークンを取得しようとすると、APIから以下のようなエラーが返って来ます。

{
　　"errcode":40164,
　　"errmsg":"invalid ip XXX.XXX.XXX.XXX ipv6 ::ffff:XXX.XXX.XXX.XXX, not in whitelist rid: xxxxxxxx-xxxxxxxx-xxxxxxxx"
}

このように「40164」のエラーコードが返って来たらホワイトリストを確認しましょう。

APIを通じてアクセストークンを取得する

AppIDとAppSecretの両方が用意出来たら、APIを使ってアクセストークンを取得してみましょう。
アクセストークンを取得するAPIは以下の通りです。

https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid=APPID&secret=APPSECRET

上記URLの「APPID」と「APPSECRET」の部分に管理画面から確認したAppIDとAppSecretの文字列それぞれ当てはめてGETでリクエストします。PHPだとこんな感じになるでしょう。

// AppIDを設定
$app_id = "XXXXXXXX";

// AppSecretを設定
$sec_key = "YYYYYYYY";

// APIをリクエスト
$json_data = file_get_contents("https://api.weixin.qq.com/cgi-bin/token?grant_type=client_credential&appid={$app_id}&secret={$sec_key}");

// 受信したJSONデータをデコード
$token_data = json_decode($json_data, true);

// アクセストークンを表示
echo $token_data['access_token'] . "\n";

AppIDとAppSecretに間違いが無ければアクセストークンは以下のようなJSONデータとして返って来ます。

{"access_token":"ACCESS_TOKEN","expires_in":7200}

実際のアクセストークン文字列はこんな形式でとても長いです。

53_eqYLvYmUdDjq_lfNElj5gr9pG2Loo3jB7J7dNQVXT8sOSt__a7zgXSjusrfdTRsrC2nV7iB-Bf0l_Z1Yv-0w4qXPEEG4dNas9EeuJ4QNWzZ4jg1ojZPCkDJA6PQigjMwG7vvTqkre5TqfEREHAQgAJACVL

アクセストークンに関する注意点

このようにアクセストークンの取得自体はそれほど難しくはありませんが、トークンの有効期限には要注意です。
トークン取得のAPIが返してくるJSONデータには「expires_in」というデータが含まれています。これはトークンの有効期限で単位は秒です。
上記の例だと7200なので有効期限は7200秒、つまり2時間という事になります。
有効期限の間はトークンを繰り返し使う事が出来ますが、新たにトークンが発行された場合はその瞬間に以前のトークンは有効期限内であっても無効となってしまいます。
その為、テンセントのドキュメントでもトークンは1つのシステム内でプールする事を推奨しています。

建议公众号开发者使用中控服务器统一获取和刷新access_token，其他业务逻辑服务器所使用的access_token均来自于该中控服务器，不应该各自去刷新，否则容易造成冲突，导致access_token覆盖而影响业务；

https://developers.weixin.qq.com/doc/offiaccount/Basic_Information/Get_access_token.html

各プロセスがそれぞれ自分でトークンを取得してしまうと、処理が同時に走った場合にトークンが無効になってしまう可能性が高いです。
試しに触る段階では気にする必要はありませんが、実際にシステムを稼働させる場合には注意しましょう。
特にAppSecretを取得する際に管理画面で「重置」と表示されていた場合は既に何かのシステムがアクセストークンを取得して何かの処理をしている可能性があります。その場合にこちらでアクセストークンを更新してしまうと、そのシステムが使っているトークンが無効となって不具合に原因となりますので十分に注意しましょう。

APIテストツール

先ほどはPHPのテストコードを示しましたが、プログラムを組む環境が無い場合はテンセントが提供しているAPIテストツールを利用する事が出来ます。
【WeChatAPIテストツールURL】
https://mp.weixin.qq.com/debug/cgi-bin/apiinfo

上記テストツールは各APIのパラメータやPOSTデータをフォームに入力する事で直接APIを実行する事が出来ます。

APIテストツールの利用例
（公式アカウントメニューをAPIを通じて変更している様子）

「テストツール」という名称ですが、ここで実行した結果は直接公式アカウントやミニプログラムに影響を及ぼします。上記利用例では公式アカウントのメニューを変更していますが、このように公式アカウントなどの設定を変更するAPIをこのツールで実行すると実際の公式アカウントのメニューが変更されてしまいます。
このツールを通してアクセストークンを取得する事も出来ますが、その場合も実際に使えるアクセストークンを更新してしまう為、それ以前に発行されたトークンが無効となります。
このツールの利用も十分に注意しましょう。