ガイドAPIリファレンス
ガイド
  1. API開発ガイドの追跡

利用開始

このセクションでは、HERE Tracking APIの使用を速やかに開始する方法について説明します。このAPIはトラッキングバックエンドプラットフォームへのプログラムによるアクセスを提供します。

📘

注

HERE APIのすべてのユーザーは、HEREの認証資格情報を取得する必要があります。次に、これらの資格情報を使用してOAuthトークンを取得します。資格情報はユーザーごとに割り当てられます。

HEREアカウントを取得する

組織管理者からの招待状を通じて、または弊社に連絡して利用を開始して、HEREプラットフォームへのアクセスを入手します。

  • 会社がすでにHEREプラットフォーム組織を設立している場合は、組織への参加に招待できる管理者に連絡してください。
  • 会社がまだHEREプラットフォーム組織を設立していない場合は、当社までお問い合わせください。

トラッキングプロジェクトを作成する

HERE Tracking APIを使い始めるには、トラッキングプロジェクトが必要です。HEREプラットフォーム組織にトラッキングプロジェクトを作成するには、次の手順を実行します。

  • HEREプラットフォームポータルでHEREプラットフォーム組織にログインします。
  • 新しいプロジェクトを作成します。[[ランチャー] > [プロジェクトマネージャー] > [新しいプロジェクトを作成]](https://platform.here.com/management/projects/create)に移動します。
  • プロジェクトを開き、[Allow access to resources outside of project](プロジェクト外のリソースへのアクセスを許可) をクリックしてトグルをオンにします。
  • プロジェクト設定で[リソース] > [サービス]に移動し、[サービスをリンク]をクリックして[HERE Tracking Prd](HERE Tracking本番環境) を選択します。トラッキングサービスはHERE基本プランには含まれていません。トラッキングサービスのライセンスを取得するには、HERE営業担当にお問い合わせください。
📘

注

プロジェクトが作成され、サービスがリンクした後、Tracking APIがプロジェクトへのリクエストを許可するまで数分かかることがあります。

  • トラッキングプロジェクトを初期化するには、ProjectAdminロールを持つプロジェクトユーザーのプロジェクトスコープトークンを取得し、GETリクエストを/registry/v2/licensesエンドポイントに送信します。このエンドポイントの詳細については、「APIリファレンス」を参照してください。このリクエストに対するレスポンスにはappIdが含まれており、これを使用してプロジェクトにデバイスをプロビジョニングできます。

    tcHost="tracking.hereapi.com"
userEmail="<user's email in the organization>"
userPassword="<user's password>"
realm="<organization ID>"  # Example: "org000000000"
projectHrn="<project HRN>" # Example: "hrn:here:authorization::org000000000:project/assettracking"

# Get unscoped user token:
curl -X POST "https://${tcHost}/users/v2/login" \
	-H 'Content-Type: application/json' \
	-d '{"email":"'"${userEmail}"'","password":"'"${userPassword}"'","realm":"'"${realm}"'"}'
userToken="<accessToken from the response>"

# Get project scoped user token:
curl -X POST "https://${tcHost}/users/v2/tokenExchange" \
	-H 'Content-Type: application/json' \
	-d '{"accessToken":"'"${userToken}"'","scope":"'"${projectHrn}"'"}'
userScopedToken="<accessToken from the response>"

# Initialize tracking project using project scoped token:
curl -X GET "https://${tcHost}/registry/v2/licenses" \
	-H 'Content-Type: application/json' \
	-H 'Authorization: Bearer '"${userScopedToken}"

プロジェクトのメンバーシップ

トラッキングプロジェクトを作成して初期化すると、HEREプラットフォームポータルを介してプロジェクトメンバーを管理できるようになります。Tracking APIリクエストの承認はプロジェクトのメンバーシップに基づいて行われます。プロジェクトスコープトークンを用いて送信されたリクエストのみが有効です。

プロジェクト管理の詳細については、Identity and Access Managementの開発者ガイドを参照してください。

生年月日の前提条件

有効なユーザートークンを取得するには、組織に招待されたすべての新規メンバーが生年月日を設定する必要があります。ユーザーが生年月日を設定せずに/users/v2/loginエンドポイントにPOSTリクエストを送信した場合、レスポンスは412 Precondition Failedとなります。

OAuthトークンを取得する

APIへのすべてのリクエストは、有効なOAuthトークンを提供して承認を受ける必要があります。OAuthトークンは専用の認証エンドポイントから取得します。APIにはユーザー用とデバイス用に、独立した認証エンドポイントがあります。

  • ユーザーはメールアドレスとパスワードを渡すことで、/users/v2/loginエンドポイントからスコープ設定されていないユーザーOAuthトークンを取得します。このエンドポイントの詳細については、「APIリファレンス」を参照してください。
  • ユーザーはスコープ設定されていないユーザーOAuthトークン (accessToken) とHEREプラットフォームのプロジェクトHRN (スコープ) を渡すことで、/users/v2/tokenExchangeエンドポイントからプロジェクトスコープのユーザーOAuthトークンを取得します。このエンドポイントの詳細については、「APIリファレンス」を参照してください。プロジェクトHRNとその取得方法の詳細については、「HRN」を参照してください。
  • デバイスはdeviceIdとdeviceSecretを渡して/v2/tokenエンドポイントからデバイスOAuthトークンを取得します。このエンドポイントの詳細については、「APIリファレンス」を参照してください。デバイストークンはIngestion APIで使用します。

アプリケーションのトークン

HEREプラットフォームプロジェクトはアプリケーションをメンバーにすることもできます。OLP CLIツールを使用してアプリケーションのトークンを取得できます。次のコマンドを実行して、プロジェクトスコープのクライアントトークンを取得します。

olp api token get --credentials PATH-TO-FILE --scope PROJECT-HRN

リクエストを送信する

HEREプラットフォームプロジェクトのHERE Tracking APIホスト名はtracking.hereapi.comです。これらのプロジェクトはプロジェクトスコープトークンを使用する場合にのみ使用できます。projectIdクエリパラメーターはプロジェクトスコープトークンを使用して送信されるリクエストでは不要です。

HEREプラットフォーム組織に属さないレガシートラッキングプロジェクトは、tracking.api.here.comホスト名を使用します。レガシープロジェクトはプロジェクトにスコープ設定されていないトークンでのみ使用できます。

📘

注

「HERE Tracking API開発者ガイド」では{tcHost}変数を参照していますが、これを該当するAPIホスト名に置き換えてください。

以下は/healthエンドポイントに対するリクエストのサンプルです。

curl -X GET 'https://{tcHost}/registry/v2/health'

サービスが稼働している場合、システムは次のレスポンスを返します。

{
    "message": "healthy"
}

次のステップ

先月の更新