Motive 接続：車両位置を輸送追跡に取り込む
このシステムの外で Motive の OAuth 2.0 フローを完了し、access token を Integration に貼り付け、API のベース URL はリージョン用エンドポイントを使う場合を除きデフォルトのまま、テスト・マッピング・有効化を行います。
Motive コネクタは Motive 車両群（旧 KeepTruckin）の車両位置を読み取り、TMS の追跡イベントに変換します。これにより、輸送中の貨物を車両位置で追跡できます。役割はこれだけです：車両位置の読み取りのみを行います。注文は取り込まず、配車や積載は作成せず、ドライバーログや運転時間の記録は読まず、Motive へは何も書き戻しません。1 接続は 1 つの Motive access token で動作します。
前提条件#
- 位置を報告する車両がある Motive 車両アカウントと、追跡したい車両が Motive に設定済みであること。
- このシステムの外で Motive の OAuth 2.0 authorization_code フローを完了できること。gomotive.com/oauth/authorize で認可し、gomotive.com/oauth/token でコードを交換します。この接続にはシステム内の認可ボタンはありません。取得済みの access token を持ってきて貼り付けます。
- token に車両位置の権限が必要です。その権限がない場合、テストは MISSING_SCOPE を返します。テスト前に Motive Developer Portal で App の権限を確認してください。
- 車両群がデフォルトの Motive API アドレスを使うか、リージョン用エンドポイントを使うかが分かっていること。ほとんどの車両群はデフォルトを使い、base_url は空のままにします。
認証情報の取得#
- このシステムの外で Motive の OAuth 2.0 フローを開始します：gomotive.com/oauth/authorize を開き、Motive App に設定された authorization_code フローに従って、車両 App のアクセスを承認します。
- gomotive.com/oauth/token で認可コードを交換し、access token を取得します。token は長い文字列で、入力手順に示す形式で、eyJraWQiOiIyMDIwXzEi のような文字で始まります。
- access token 全体を一度にコピーし、貼り付けられるよう用意します。短くしたり、スペースや改行を加えたりしないでください。切り取られた token は INVALID_TOKEN を返します。
- この token には有効期限があることを覚えておいてください。期限が切れても、この接続が代わりに更新することはできません。同じ OAuth authorization_code フローを再度実行し、新しい token を貼り付けます。車両の報告が止まる前に更新を計画してください。
Integration への入力#
- Integration → コネクタマーケットプレイス → Motive → 新規接続 を開きます。
- token、必須、OAuth2 access token：gomotive.com/oauth/token で交換した access token 全体を貼り付けます。例：eyJraWQiOiIyMDIwXzEi で始まる長い文字列。パスワード型のフィールドで、秘密情報として保存されます。
- base_url、任意、API ベース URL：空のままにするとデフォルトの https://api.gomotive.com が使われます。車両群が Motive のリージョン用 API エンドポイントを使う場合のみ入力し、その場合は Motive が提示したエンドポイントアドレスをそのまま入力してください。
接続テスト#
接続テストをクリックします。token が入力されている場合、テストは実際の読み取り専用リクエストを 1 回送信します：GET {base_url}/v2/vehicle_locations、token を Bearer 認証情報として使用し、タイムアウトは 12 秒です。200 の応答は、token が受け入れられ、車両位置エンドポイントに到達できることを意味します。401 の応答は INVALID_TOKEN として返ります。token が無効か期限切れです。403 の応答は MISSING_SCOPE として返ります。token に車両位置の権限がありません。時間内に応答しないリクエストは TIMEOUT として返ります。コードが示す原因を直して再テストしてください。テストが Motive のデータを変更することはありません。
Mapping / テンプレート選択#
Motive 標準の Mapping を選択します。車両群について返された各車両位置を、その車両の TMS 追跡イベントに変換します。これにより、位置が TMS で追跡する車両や貨物と一致します。テスト合格後、1 回読み取りを実行し、路上にあることが分かっている車両を 1 台比較してください。ここでの最新位置と Motive の同じ車両を照合します。位置が一致すれば Mapping は正しく、有効化できます。
有効化#
有効化後、接続はお使いの token で Motive から車両位置を読み取り、車両群の最新位置で TMS 追跡を更新し続けます。最初は Runs / Logs で読み取りを確認し、数台の車両を Motive と照合してから無人運用に移してください。また token の有効期限を記録し、期限内に更新できるようにしてください。
この接続が行わないこと：Motive から注文や積載を取り込まず、配車を作成・変更せず、ドライバーログ、運転時間、燃料記録は読まず、位置やその他のデータを Motive に送信しません。これらは引き続き Motive 自体で、または実際の作業を行うシステムで処理してください。
よくある質問#
テストが INVALID_TOKEN（401）で失敗する
Motive が token を拒否しました。無効か期限切れです。OAuth authorization_code フローの access token は永久には使えず、コピー時に切り取られた token も同じように拒否されます。テストでは切り取りと期限切れを区別できません。
Motive の OAuth authorization_code フローを再度実行してください（gomotive.com/oauth/authorize で認可し、gomotive.com/oauth/token でコードを交換）。新しい access token を全文コピーし、token フィールドに貼り付けて保存し、再テストします。この接続に更新ボタンはありません。新しい token は常に新しい OAuth の実行から得られます。
テストが MISSING_SCOPE（403）で失敗する
token 自体は受け入れられましたが、車両位置の権限がないため、Motive は車両位置の読み取りを許可しません。入力した値の問題ではありません。token の発行時に App へその権限が付与されていなかったのです。
Motive Developer Portal を開き、App の権限を確認して、車両位置へのアクセスが付与されていることを確認してください。その後 OAuth フローを再度実行し、その権限を持つ token を発行し、新しい token を貼り付けて再テストします。
テストが TIMEOUT で失敗する
車両位置リクエストが 12 秒以内に応答しませんでした。これは Motive API への到達性の問題です。base_url の誤り、車両群に応答しないリージョン用エンドポイント、または Motive API の一時的な遅延が考えられます。token が間違っている証拠ではありません。
まず base_url を確認してください。車両群が本当にリージョン用エンドポイントを使う場合を除き、空にしてデフォルトの https://api.gomotive.com を使います。その後再テストします。デフォルトアドレスでもタイムアウトが繰り返される場合は、少し待って再試行し、サポートを求める際は Runs / Logs の失敗時刻を控えてください。
以前は接続できていたのに、車両位置が更新されなくなった
最も多い原因は access token の有効期限切れです。接続には古い token が残り、自動で更新できないため、読み取りが失敗し始めます。通常ログには INVALID_TOKEN が出ます。接続の他の設定は何も変わっていません。
OAuth authorization_code フローを再度実行し、新しい access token を token フィールドに貼り付けて保存し、テストします。テストに合格すると位置の更新が再開します。今回は新しい有効期限を記録し、次回は期限前に更新してください。
接続済みだが、1 台の車両の位置が表示されない
接続は Motive が持つ車両群の位置を返します。その車両について Motive 自体に現在の位置がない場合（車両の電源が切れている、カバー範囲外、報告していない）このシステムに表示できるものはありません。正常な接続でも、Motive が持っていない位置を作り出すことはできません。
まず Motive で同じ車両を確認してください。Motive に現在の位置があるのにこのシステムにない場合は、手動読み取りを実行し、Runs / Logs で車両を比較し、接続を再テストします。Motive にも何も表示されない場合は、その車両の Motive 側の報告を直してください。
Motive から注文や配車が入ってこないのはなぜですか？
このコネクタは車両位置のみを読み取るためです。注文、積載、配車は Motive から読める対象ではないため、ここで注文リストが空なのは想定どおりの動作で、接続の故障ではありません。
注文や配車は、引き続き実際の作業を行うシステムで作成・管理してください。この接続は、本来の用途に使ってください：TMS 追跡で、それらの貨物を運ぶ車両を追跡することです。