HTTP クライアントから HULFT Square の REST API ジョブを呼び出す際に躓いたので、その解決策を共有します

Posted at 2024-12-08

HULFT Square の REST API ジョブを呼び出したい！

具体的には、次のリンク先記事を参考にして、Python の Requests ライブラリを使って、HULFT Square に対して REST 形式で Web API をたたきたい。

本記事は、上記の必要性に駆られた方向けとなります。

概要

HULFT Square では、HTTP クライアントから REST API ジョブを呼び出す際の認証方式に、Bearer 認証を採用しています。

Bearer 方式でアクセストークンを設定したのに、なぜか HULFT Square の REST API ジョブに対するリクエストで、HTTP 401 Unauthorized エラーになってしまう、、

筆者が開発を行う中で上記の課題で躓いたため、その解決策を紹介します。

まずは結論

今回の私のケースでは、冒頭で張り付けたものと同じ記事において、「2. 1 アクセストークンを更新する」という部分で説明されている、リフレッシュトークンを使用してアクセストークンを更新するための追加実装が必要でした。

アクセストークンの更新が必要である理由は、アクセストークンの有効期限が切れてしまっているためとなります。

では、アクセストークンの有効期限が切れている場合、どのように更新することになるのか。
下記がそのサンプルコードとなります。

payload_refresh_token = {
    "refreshToken":"リフレッシュトークン" // リフレッシュトークンは下記の手順6-1で生成後、取得可能です。
}
response_refresh_token = requests.post(
    "https://app.square.hulft.com/v1/rest-api-token", // POST 先のエンドポイント URL
    data=json.dumps(payload_refresh_token), // リフレッシュトークンをリクエストボディにセット
    headers={"Authorization": f"Bearer {access_token}"} // Bearer 形式で access_token をリクエストヘッダにセット
)

更新リクエストの結果得られた更新後のアクセストークンは、次のようなサンプルコードで取得します。

refreshed_access_token = response_refresh_token.json().get("accessToken")

上記結論が適用される場合の前提条件

※下記の条件を順番に満たすことで、HTTP クライアントから HULFT Square の REST API ジョブを呼び出すための環境準備が整います。従って、環境準備ができていない場合は下記が参考になると思います。
※下記を記載するにあたり参考にしたのは、次のリンク先の「0. 事前準備」と「1. Login APIでアクセストークンを取得する」です。詳細はリンク先を参照ください。

HULFT Square 側でスクリプトを作成している
HULFT Square 側で API プロジェクトを作成している
HULFT Square 側で API プロジェクトにリソースを追加している
HULFT Square 側で APIクライアントの作成している
HULFT Square 側で REST API ジョブの作成している
HTTP クライアント側から Login API でアクセストークンを取得できる
1. HULFT Square 側でアクセストークンを生成している（次の記事の「アクセストークンを生成」で手順が紹介されているので、参考にしてください）
  https://www.hulft.com/help/ja-jp/HULFTSquare/Content/TOP/GettingStarted/MyProfile.htm#SC_access_token
2. Login API でアクセストークンを取得できる（一例として、次のサンプルコードのようなリクエスト形式となります）
```
 payload_access_token = {
     "email":"メールアドレス",
     "password":"パスワード"
 }
 response_access_token = requests.post(
     "https://app.square.hulft.com/v1/users/login", // POST 先のエンドポイント URL
     data=json.dumps(payload_access_token), // ログイン情報をリクエストボディにセット
     headers={"Content-Type": "application/json"} // Content-Type をリクエストヘッダにセット
 )
```
  ※リクエストの結果得られたレスポンスのアクセストークンは、次のようなサンプルコードで取得します。
```
 access_token = response_access_token.json().get("accessToken")
```
  ※以降、API にアクセスする場合は、Login API で取得したアクセストークン（上記例における access_token）を Authorization Header に指定して、アクセスの許可を得る必要があります。一例として、次のサンプルコードのようなリクエストヘッダとなります。
```
 headers={
     "Content-Type": "application/json",
     "Authorization": f"Bearer {refreshed_access_token}",
     "X-HSQ-Async": "true"
 }
```

その他の豆知識

REST API ジョブを非同期で実行するためには、リクエストヘッダに "X-HSQ-Async" を "true" で設定します。

headers={
    "X-HSQ-Async": "true"
}

※「REST APIジョブを非同期で実行したい場合」を参照ください。

これによって、HULFT Square の REST API ジョブのリクエストタイムアウトエラー（29秒でタイムアウト）を避けることができます。

また、API トークンの有効期限は編集可能です。
アクセストークンの有効期限はデフォルトで60分、最大1日です。
リフレッシュトークンの有効期限はデフォルトで30日、最大で1年です。

You get articles that match your needs
You can efficiently read back useful information
You can use dark theme

What you can do with signing up