OAuth 2.0で認証する方法

HEREでは認証のためAPIキーまたはOAuth 2.0ベアラーアクセストークンを作成できます。

📘
注
信頼されるドメインではトークンが適用されません。

トークン資格情報は、ベアラーアクセストークンのOAuth 2.0業界標準プロトコルに準拠しています。HERE では、アプリで最大 24 時間使用されるこれらのセキュアなアクセストークンを取得するための REST API を提供しています。古いトークンを使用して HERE API を呼び出すと、401 Unauthorized エラーが表示されます。

API はアクセストークンをリクエストし、この API にはサービスの健全性を保護するための固定制限があります。appIdごとの制限は、デフォルトで15分間に25,000リクエストに設定されており、Here Account APIへのすべての呼び出しで1分間に1666リクエストに制限されます。

前提条件

HERE は次のオペレーティングシステムをサポートします。

Windows 10
Linux (Ubuntu 18.04)
macOS Sierra 以降

OLP CLIには、Javaランタイム環境 (JRE) バージョン1.8.0_91以降が必要です。wingetを使用してOLP CLIをインストールした場合、OpenJDK 17イメージがすでにインストールされている可能性が高く、その場合はJREを別途インストールする必要はありません。

OAuth 2.0トークンを取得するには、次の手順を実行します。

ステップ1 - アプリを登録して資格情報を取得する

OAuth 2.0トークンを使用するには、HEREプラットフォームにアプリを登録してから、資格情報を取得する必要があります。

📘
注
関連する認証資格情報はアプリに固有のものであり、ユーザー権限やグループメンバーシップを継承しません。

アプリを登録する

ローカル開発環境で、ホームディレクトリ内に.hereフォルダーを作成します。
- Mac/Linuxをお使いの場合、これは$HOME/.hereになります。
- Windowsユーザーの場合、C:\%HOMEPATH%\.hereとなります (ホームディレクトリがCドライブにある場合)。
HEREプラットフォームにサインインします。
ランチャから[アクセスマネージャー]を開きます。
[アプリ] タブで、[新しいアプリを登録] をクリックし、求められた情報を入力します。
[登録]をクリックします。プラットフォームで、一意のアプリ ID を持つ新しいアプリが作成されます。

資格情報を取得する

[資格情報]タブで、[OAuth 2.0]を選択し、[資格情報を作成]をクリックします。
開いたダイアログボックスで[ダウンロード]をクリックして、アプリのcredentials.propertiesファイルをダウンロードします。

このファイルには、ユーザーID、アプリID (here.client.idという名前)、OAuth 2.0トークンエンドポイントのURL、アクセスキーID、アクセスキーシークレットが含まれています。 なお、[Close](閉じる) をクリックすると、アクセスキーIDとアクセスキーシークレットにアクセスできなくなります。

最初のステップで作成した.hereフォルダーにcredentials.propertiesファイルをコピーします。

credentials.propertiesファイルには、OLP CLIとライブラリがプラットフォームへのアクセスを管理するために使用するプラットフォーム資格情報が含まれています。また、ファイルに含まれるOAuth 2.0トークン資格情報を使用して、さまざまなHERE REST APIに対して認証された呼び出しを行うことができます。

OLP CLIの使用方法の詳細については、「Command Line Interface Developer Guide」(コマンドラインインターフェース開発者ガイド) を参照してください。

ステップ2 - OLP CLIをインストールする

お好みの方法でOLP CLIをインストールします。

ステップ3 - トークンを取得する

アプリを登録したら、OAuth 2.0トークンを使用してリクエストを認証できます。アプリは最大2つのトークンを使用できます。

OLP CLIを使用してトークンを取得できます。詳細については、「HERE OLP CLI - ユーザーガイド」を参照してください。

🚧
注意
資格情報は非公開にし、ワークステーションとユーザー間、またはGitHubなどのサイトのパブリックリポジトリでは共有しないでください。

トークンを取得するには、次の手順を実行します。

HEREプラットフォームにサインインします。
ランチャから[アクセスマネージャー]を選択します。
[アプリ] をクリックし、以前に登録したアプリを選択します。
[資格情報] タブから OAuth 2.0 を選択します。
[Create Credentials](資格情報を作成) をクリックします。
開いたダイアログボックスで[ダウンロード]をクリックして、credentials.propertiesファイルをダウンロードします。なお、[Close](閉じる) をクリックすると、アクセスキーIDとアクセスキーシークレットにアクセスできなくなります。
デフォルトプロフィールを作成して資格情報を関連付けるには、次のコマンドを実行します。

olp credentials import default credentials.properties

トークンを取得するには、OLP CLI JARファイルがあるディレクトリに移動し、次のコマンドを実行します。

olp api token get

資格情報が正しく設定されている場合は、返されたトークンと、次のような出力が表示されます。

Token: eyJhbGciOiJSUzUxMiIsImN0eSI6IkpXVCIsImlzcyI6IkhFUkUiLCJhaWQiOiJtekxjYjFyTDhuc2t2RFFwQ0ZFRiIs
ImlhdCI6MTUyMTgwNjYyOCwiZXhwIjoxNTIxODkzMDI4LCJraWQiOiJqMSJ9.ZXlKaGJHY2lPaUprYVhJaUxDSmxibU1pT2lKQk
1qVTJRMEpETFVoVE5URXlJbjAuLmtGc0JMODJibEUxTHhCS1M3MEctcFEuZHhsb2psaklEQmdNVEdoMEFKMHAzUU9yeE9INXdhd
1hkWjVSLS1Kdkc3VFBoUkRWY3owcUFYZ0V2Y3kwOGpMdzBCR09sNjJfZ2pxeUNuLXhET3JtZV8xNUlkV0tJN2VxTUpZNTNJelRx
ZjhUSzdVVHlEUlJFVnBLRW5BN2FvR2MubFViMTNGYWdKMlVGZXVQZnZsVG44Y2JqTzdtbF9ncGpLamFUN0xmZFF0UQ.EPYB9Rdy
jCHFxrqpaEBWkPzhPmFrAPBKlkt8SQpcI0k71mH_vC6txh6Uv1NVQC4xYyWG7ueq5mb4mcQh1sCorcv15GwIH1R0v0NR_CRPh-M
DNSFtg8HNnWyC1ePsfUGpSqjucQW8RMdbsU03wDO50Pr3ctQI4BZrxiU4HW6tdQq9_TinizujACzE-LMZ6FlFAb6pPB8TDsFlY3
9OmBFXEanaPvZwE01dKjE1K_A_G1_TiJzWo4vwuNeD54HfmOf6hN1IE8-CCSKRoIFoIBiVNqqzyCybyovRlSCWzSaTNz4v9BD7N
2lDgEuBlpn3q0qTFppZzjEvzv3RicGrCC_tmB
Token Expires at: 2018-03-24T14:03:48.100Z

ステップ4 - トークンを使用する

トークンを取得したら、HEREサービスへのリクエストごとにOAuth 2.0トークンを取得するようにアプリをコーディングする必要があります。まず、トークンをベアラートークンとしてRESTリクエストのHTTP承認ヘッダーに含めます。

Authorization: Bearer <token>

次の例に示すように、このトークンを使用して、API RESTリクエストでHEREサービスにアクセスできます。 RESTリクエストの例 以下は、GETメソッドを使用して、ベルリンの地点から500メートル以内の駐車場のリストを取得する例です。 サンプルリクエスト

URL https://parking-v2.cc.api.here.com/parking/facilities.jsonは、駐車場データをJSON形式で取得するためのエンドポイントを指定しています。
クエリパラメーター?prox=51638,13.38244,500は、検索用の地理座標 (緯度と経度) と半径 (500メートル) を示します。
-H "Authorization: Bearer {YOUR_TOKEN}"の行は承認ヘッダーを追加しています。実際のAPI呼び出しでは、{YOUR_TOKEN}は認証用の有効なアクセストークンに置き換えます。

curl GET 
https://parking-v2.cc.api.here.com/parking/facilities.json
?prox=52.51638,13.38244,500
-H "Authorization: Bearer {YOUR_TOKEN}"

サンプルレスポンス レスポンスでは、駐車場の詳細を生成します。

トップレベルのオブジェクトには、2つのプロパティが含まれます。

プロパティ	定義
`hasMore`	使用可能な施設が他にあるかどうかを示すブール値。この例では、値は`false`と返されています。
`facilities`	施設詳細の配列を保持するオブジェクト。

facilityオブジェクトには、営業時間、住所、連絡先情報など、レストランに関するさまざまな情報が含まれています。

{
   "hasMore":false,
   "facilities":{
      "facility":[
         {
            "open24x7":true,
            "facilityDetails":{
               "openingHours":{
                  "openNow": true,
                  "regularOpeningHours":[
                     {
                        "daymask":127,
                        "period":[
                           {
                              "from":"00:00:00",
                              "to":"24:00:00"
                           }
                        ]
                     }
                  ],
                  "annualOpenings":[
                  ]
               },
               "driveMaxHeight":1.8,
               "facilityType":{
                  "name":"Parking Facility",
                  "id":"1"
               },
               "facilityOperator":"APCOA GmbH",
               "facilityLevels":2,
               "facilityInfrastructures":{
                  "name":[
                     "handicappedparkingspaces",
                     "securitymanned",
                     "elevators",
                     "light"
                  ]
               },
               "facilityAdministration":{
                  "name":[
                     "Monitored",
                     "Gate"
                  ]
               },
               "facilityRestrictions":{

               },
               "paymentMethods":[
                  {
                     "name":"Cash - EUR",
                     "id":"CASH"
                  }
               ]
            },
            "facilityAvailability":{
               "spacesTotal":173,
               "available":true,
               "pricing":{
                  "price":[
                     {
                        "priceGroup":0,
                        "amount":2.0,
                        "currency":"EUR",
                        "unit":30,
                        "daymask":127,
                        "minMinutes":0,
                        "maxMinutes":30,
                        "textRepresentation": [
                          {
                            "text": [
                              "First 30 minutes",
                              "Per 30 minutes",
                              "Every day"
                            ],
                            "language": "en-US"
                          }
                        ]
                     },
                     {
                        "priceGroup":1,
                        "amount":4.0,
                        "currency":"EUR",
                        "unit":60,
                        "daymask":127,
                        "minMinutes":31,
                        "maxMinutes":60,
                        "textRepresentation": [
                          {
                            "text": [
                              "Over 31 minutes",
                              "Max 1 hour",
                              "Per hour",
                              "Every day"
                            ],
                            "language": "en-US"
                          }
                        ]
                     },
                     {
                        "priceGroup":2,
                        "amount":38.0,
                        "currency":"EUR",
                        "unit":1440,
                        "daymask":127,
                        "minMinutes":61,
                        "maxMinutes":1440,
                        "textRepresentation": [
                          {
                            "text": [
                              "Over 1 hour and 1 minute",
                              "Max 24 hours",
                              "Per day",
                              "Every day"
                            ],
                            "language": "en-US"
                          }
                        ]
                     }
                  ]
               },
               "lastUpdateTimestamp":"2016-06-06T06:50:31.000Z"
            },
            "address":{
               "city":"Berlin",
               "country":"DEU",
               "region":"Berlin",
               "street":"Unter den Linden",
               "streetNumber":"77",
               "postalCode":"10117"
            },
            "contacts":{
               "phone":[
                  {
                     "value":"+4971130570305",
                     "label":"PHONE"
                  }
               ]
            },
            "distance":166,
            "position":{
               "latitude":52.51631,
               "longitude":13.37999
            },
            "name":"Hotel Adlon",
            "id":"276u33db-e63737ae997c4a1ab5a19c50a63af49e",
            "lastUpdateTimestamp":"2016-05-31T01:04:46.015Z",
			"timeZone":"Europe/Berlin"
         },
         {
            		---removed to shorten document
         }
      ]
   }
}

次のステップ

認証と承認の詳細については、「IDとアクセス管理許可API v1.1 APIリファレンス」および「IDとアクセス管理許可API v1.1 APIリファレンス」を参照してください。