例を読む

このページでは、異なるプラットフォームでサンプル読み取りプロジェクトをビルドおよび実行し、パーティション メタデータを使用してカタログとパーティション データ、および HERE Data SDK for C++ を取得する方法について説明します。

サンプルプロジェクトを実行する前に、 HERE platform に認証します。

1. [ アプリとキー ] ページで、アプリのアクセスキー ID とアクセスキーのシークレットをコピーします。

   アクセスキー ID およびアクセスキーシークレットを取得する方法については、『 Identity & Access Management 開発者ガイド』の「アプリケーションの登録」セクションを参照してください。

2. で examples/main.cpp、プレースホルダーをカタログのアクセスキー ID 、アクセスキーシークレット、および HERE リソースネーム （ HERE リソースネーム ）に置き換えます。

   注

   コマンド ラインオプションを使用して、これらの値を指定することもできます。

   AccessKey access_key{};  // Your access key ID and access key secret.
   

Linux でビルドして実行します

Linux でサンプルプロジェクトをビルドして実行するには、次の手順に従います。

1. CMake ターゲットの例を有効にします。

   mkdir build && cd build
   cmake -DOLP_SDK_BUILD_EXAMPLES=ON ..
   

2. build フォルダで、サンプルプロジェクトを構築します。

   cmake --build . --target dataservice-example
   

3. サンプルプロジェクトを実行します。

   ./examples/dataservice-example --example read --key_id "here.access.key.id" --key_secret "here.access.key.secret" --catalog "catalog"
   

4. ( オプション ) 他のパラメータを使用して例を実行するには、 help コマンドを実行してから、必要なパラメータを選択します。

   ./examples/dataservice-example --help
   

サンプルプロジェクトをビルドして実行すると、次の情報が表示されます。

• edge-example-catalog –カタログの説明。
• versioned-world-layer –レイヤーの説明。
• Request partition data - Success, data size - 3375 –要求されたパーティションから取得されたデータのサイズを表示する成功メッセージ。

[INFO] read-example - Catalog description: edge-example-catalog
[INFO] read-example - Layer 'versioned-world-layer' (versioned): versioned-world-layer
[INFO] read-example - Layer contains 1 partitions
[INFO] read-example - Partition: 1
[INFO] read-example - Request partition data - Success, data size - 3375

Android でビルドして実行できます

Android サンプルプロジェクトに Data SDK ライブラリを統合するには、次の手順を実行します。

• 前提条件を設定します
• Data SDK を構築します
• APK をビルドして実行します

前提条件

Android サンプルプロジェクトに Data SDK ライブラリを統合する前に、次の点を確認してください。

1. Android 環境を設定します。

2. で examples/android/app/src/main/cpp/MainActivityNative.cpp.in、プレースホルダーをアプリケーションのアクセスキー ID 、アクセスキーシークレット、およびカタログ HERE リソースネーム で置き換え、この例を実行するように指定 RunExampleReadします。

   アクセスキー ID およびアクセスキーシークレットを取得する方法については、『 Identity & Access Management 開発者ガイド』の「アプリケーションの登録」セクションを参照してください。

Data SDK を構築します

Android で Data SDK を構築するには、次の手順を実行します

1. OLP_SDK_BUILD_EXAMPLES をに設定 ONします。
2. （任意）テストをディセーブルにするに OLP_SDK_ENABLE_TESTINGOFFは、をに設定します。
3. 変数を使用 CMAKE_TOOLCHAIN_FILE して、 Android NDK ツールチェーンファイルへのパスを指定します。

4. 特定の Android プラットフォーム用に SDK をビルドする場合は -DANDROID_PLATFORM CMake 、フラグを使用 -DANDROID_ABI し、特定の Android アーキテクチャ用に SDK をビルドする場合は、フラグを使用します。 詳細については、NDK 固有の CMake 変数を参照してください。

   mkdir build && cd build
   cmake .. -DCMAKE_TOOLCHAIN_FILE=$NDK_ROOT/build/cmake/android.toolchain.cmake -DANDROID_ABI=arm64-v8a -DOLP_SDK_BUILD_EXAMPLES=ON -DOLP_SDK_ENABLE_TESTING=OFF
   

   CMake コマンドを使用 Gradlebuild/examples/android すると、フォルダーにプロジェクトが生成されます。

5. Data SDK ライブラリを sysroot ディレクトリにインストールします。

   # If necessary, execute as sudo.
   (sudo) make install
   

APK をビルドして実行します

APK をビルドして実行するには、次の手順に従います。

1. Android Studio IDE で build/examples/android/build.gradle 、スクリプトを開きます。
2. アプリケーションのアクセスキー ID 、アクセスキーシークレット、およびカタログ HERE リソースネーム を入力します。
3. dataservice_example APK をインストールして実行します。

メイン画面に次のメッセージが表示されます。 " 例が正常に終了しました " 。

iOS でビルドして実行します

Objective-C 言語で記述された iOS サンプルプロジェクトに Data SDK ライブラリを統合するには、次の手順を実行します。

• 前提条件を設定します
• Data SDK を構築します
• アプリケーションをビルドして実行します

前提条件

iOS サンプルプロジェクトに Data SDK ライブラリを統合する前に、次のことを行います。

1. iOS 開発環境を設定するには、 Xcode およびコマンドラインツールをインストールします。

2. 外部の依存関係をインストールします。

   依存関係およびインストール手順については、 README.MD ファイルの関連セクションを参照してください。

3. で examples/ios/ViewController.mm、プレースホルダーをアプリケーションのアクセスキー ID 、アクセスキーシークレット、およびカタログ HERE リソースネーム で置き換え、この例を実行するように指定 RunExampleReadします。

   アクセスキー ID およびアクセスキーシークレットを取得する方法については、『 Identity & Access Management 開発者ガイド』の「アプリケーションの登録」セクションを参照してください。

Data SDK を構築します

iOS で Data SDK を構築するには、次の手順を実行します

1. OLP_SDK_BUILD_EXAMPLES をに設定 ONします。
2. （任意）テストをディセーブルにするに OLP_SDK_ENABLE_TESTINGOFFは、をに設定します。

3. CMAKE_TOOLCHAIN_FILE 変数を使用して、 iOS ツールチェーンファイルへのパスを指定します。

   注

   iOS ツールチェーンファイルは、 SDK と一緒に出荷 <olp-sdk-root>/cmake/toolchains/iOS.cmakeされ、の下にあります。

mkdir build && cd build
cmake .. -GXcode  -DCMAKE_TOOLCHAIN_FILE=../cmake/toolchains/iOS.cmake -DPLATFORM=iphoneos -DOLP_SDK_BUILD_EXAMPLES=ON -DOLP_SDK_ENABLE_TESTING=OFF

シミュレータの Data SDK を設定するに SIMULATORONは、 CMake 変数をに設定します。

アプリケーションをビルドして実行します

iOS でサンプルアプリケーションを実行するには、次の手順を実行します。

1. 生成された Xcode プロジェクトを開きます。

   open olp-cpp-sdk.xcodeproj
   

2. Xcode プロジェクトのスキームのリストから dataservice-example 、スキームを選択します。

3. dataservice-example ターゲットで、アプリケーションのアクセスキー ID とアクセスキーシークレットを指定します。

4. サンプルアプリケーションをビルドして実行します。

メイン UI 画面に次のメッセージが表示されます。 " 指定したカタログからのパーティション データの読み取りが正常に完了しました " 。 詳細については、デバイスログを確認してください。

エラーメッセージが表示された場合は、エラーの詳細な説明について、デバイスのログを確認してください。 エラーメッセージの例 : " 指定したカタログからデータを読み取ることができませんでした。 "

仕組み

カタログメタデータを取得します

Catalog メタデータには、カタログとそのレイヤーを記述する構成のリストが含まれています。 カタログの設定情報には、次のメタデータが含まれています。

• 名前
• HERE リソースネーム （ HERE リソースネーム ）
• 説明
• 所有者
• バージョン
• レイヤー情報

カタログメタデータを取得するには、次の手順

1. OlpClientSettings オブジェクトを作成します。

   手順については、「プラットフォームクライアント設定を作成する」を参照してください。

2. CatalogClient ステップ 1 でカタログの HERE リソースネーム およびプラットフォームクライアント設定を使用してオブジェクトを作成します。

   olp::dataservice::read::CatalogClient catalog_client(
           olp::client::HRN(kCatalogHRN), client_settings);
   

3. CatalogRequest オブジェクトを作成します。

   auto request =
   olp::dataservice::read::CatalogRequest();
   

4. （任意）必要なパラメータを設定します。 たとえば、請求タグを設定するに WithBillingTag は、パラメータを設定します。

   request.WithBillingTag("MyBillingTag");
   

5. GetRequestCatalogRequest パラメーターを使用してメソッドを呼び出します。

   auto future = catalog_client.GetCatalog(request);
   

6. CatalogResponse 今後の対応をお待ちください。

   olp::dataservice::read::CatalogResponse catalog_response = future.GetFuture().get();
   `
   

CatalogResponse このオブジェクトは、完了した操作の詳細を保持し、操作の成功および結果のデータへのアクセスを判断するために使用されます。

• IsSuccessful() –操作が成功した場合は、を返し trueます。 それ以外の場合は、を返します false
• GetResult()–操作が成功すると、次の結果データが返されます。 olp::dataservice::read::CatalogResult
• GetError() – olp::client::ApiError オブジェクトのエラーの結果としてエラー情報が含まれます。

if (catalog_response.IsSuccessful()) {
    auto response_result =
        catalog_response.GetResult();
    // Handle success
} else {
    auto api_error = catalog_response.GetError();
    // Handle fail
}

CatalogResult このクラスには、関連するカタログの詳細を取得するために使用される次のメソッドが含まれています。

• GetId –カタログ ID を返します。
• GetHrn –カタログを返し HRNます。
• GetName –カタログ名を返します。
• GetSummary –カタログの概要を返します。
• GetDescription –カタログの完全な説明を返します。
• GetCoverage –カタログのカバレッジエリアを返します。
• GetOwner –カタログ所有者の ID を返します。
• GetTags –カタログタグのコレクションを返します。
• GetBillingTags –カタログに設定されている請求タグを返します。
• GetCreated –カタログ作成時間を返します。
• GetLayers –カタログに含まれているレイヤーの詳細を返します。
• GetVersion –現在のカタログバージョン番号を返します。
• GetNotifications –カタログの通知ステータスを返します。

ApiError このクラスには、発生したエラーの詳細を取得するために使用される次のメソッドが含まれています。

• GetErrorCode – ErrorCode によって定義された値を返し olp::client::ErrorCode enumます。 詳細については、を参照 ErrorCode.hしてください。
• GetHttpStatusCode – HTTP 応答コードを返します。
• GetMessage –発生したエラーの説明をテキストで返します。
• ShouldRetry – true この操作を再試行できる場合に返します。

パーティション メタデータを入手します

パーティション メタデータは、パーティションに関する次の情報で構成されています。

• データ ハンドル
• ID
• バージョン
• データサイズ
• 圧縮されたデータサイズ
• チェックサム

パーティション メタデータを取得するには :

1. OlpClientSettings オブジェクトを作成します。

   手順については、「プラットフォームクライアント設定を作成する」を参照してください。

2. レイヤータイプに応じて、ステップ 1 で HERE リソースネーム （ HERE リソースネーム ）、レイヤー ID 、レイヤーバージョン、およびプラットフォームクライアントの設定を使用して、バージョン管理されたクライアントまたはボラタイル レイヤークライアントを作成します。

   カタログバージョンを指定しない場合は、最新バージョンが使用されます。 クライアントへの最初の API 呼び出しで指定したフェッチオプションに応じて GetLatestVersion 、メソッドは次のいずれかの方法で自動的に最新バージョンを取得します。

   • OnlineIfNotFound fetch オプションでは、がネットワークを照会し、エラーが発生した場合はキャッシュを確認します。 オンラインバージョンがキャッシュバージョンよりも高い場合、キャッシュバージョンが更新されます。
   • OnlineOnly fetch オプションの場合、はネットワークのみを照会します。
   • CacheOnly fetch オプションでは、キャッシュのみを確認します。

   olp::dataservice::read::VersionedLayerClient layer_client(
      olp::client::HRN(kCatalogHRN), layer_id, version, client_settings);
   

3. PartitionsRequest 次のいずれかのフェッチオプションを使用してオブジェクトを作成します。

   • ( デフォルト ) 要求されたリソースがキャッシュに見つからない場合にネットワークを照会するに OnlineIfNotFoundは、を使用します。
   • キャッシュの検索をスキップして、ただちにネットワークにクエリーを送信するに OnlineOnlyは、を使用します。
   • キャッシュの検索に失敗した場合にただちに戻るに CacheOnlyは、を使用します。
   • ( 用ではあり VersionedLayerClientCacheWithUpdateません ) 要求されたキャッシュリソースが見つかった場合にそのリソースを戻し、バックグラウンドでキャッシュを更新するには、を使用します。

   auto request =
   olp::dataservice::read::PartitionsRequest()
                           .WithBillingTag("MyBillingTag")
                           .WithFetchOption(FetchOptions::OnlineIfNotFound);
   

4. GetPartitionsPartitionRequest パラメーターを使用してメソッドを呼び出します。

   auto future = layer_client.GetPartitions(request);
   

   注

   レイヤーでパーティションキーをタイル ID として使用している場合、大量のデータが原因でこの操作が失敗することがあります。

5. PartitionsResponse 未来を待っていてください。

   olp::dataservice::read::PartitionsResponse partitions_response =
       future.GetFuture().get();
   

PartitionsResponse このオブジェクトは、完了した操作の詳細を保持し、操作の成功および結果のデータへのアクセスを判断するために使用されます。

• IsSuccessful() –操作が成功した場合は、を返し trueます。 それ以外の場合は、を返します false
• GetResult()–操作が成功すると、次の結果データが返されます。 olp::dataservice::read::PartitionsResult
• GetError() – olp::client::ApiError オブジェクトのエラーの結果としてエラー情報が含まれます。

if (partitions_response.IsSuccessful()) {
    const olp::dataservice::read::PartitionsResult& response_result =
        partitions_response.GetResult();
    // Handle success
} else {
    // Handle fail
}

PartitionsResult このクラスには GetPartitionsolp::dataservice::read::model::Partition 、そのタイプのパーティション メタデータオブジェクトのコレクションを返すメソッドが含まれています。

Partition このクラスにはパーティション メタデータが含まれ、次のメンバーが公開されます。

• GetChecksum –パーティションチェックサムを返します。
• GetCompressedDataSize –圧縮されたパーティション データのサイズを返します。
• GetDataHandle - GetData 関数がパーティション データを取得するために使用できるハンドルを返します。
• GetDataSize –パーティション データのサイズを返します。
• GetPartition –パーティション ID を返します。
• GetVersion –パーティションの最新のカタログバージョンを返します。

バージョン付レイヤーからデータを取得します

バージョン付レイヤーから任意のデータバージョンを要求できます。 バージョン付レイヤーから特定のバージョンのデータを要求すると、応答で受信したパーティションのバージョン番号が、要求したものよりも小さい可能性があります。 レイヤーまたはパーティションのバージョンは、そのレイヤーまたはパーティションが最後に更新されたカタログのバージョンを表します。

バージョン付レイヤーからデータを取得するには、次の手順に従います。

1. OlpClientSettings オブジェクトを作成します。

   手順については、「プラットフォームクライアント設定を作成する」を参照してください。

2. VersionedLayerClient ステップ 1 で、レイヤー、レイヤー ID 、カタログバージョン、およびプラットフォームクライアント設定を含むカタログの HERE リソースネーム （ HERE リソースネーム ）を使用してオブジェクトを作成します。

   カタログバージョンを指定しない場合は、最新バージョンが使用されます。 クライアントへの最初の API 呼び出しで指定したフェッチオプションに応じて GetLatestVersion 、メソッドは次のいずれかの方法で自動的に最新バージョンを取得します。

   • OnlineIfNotFound fetch オプションでは、がネットワークを照会し、エラーが発生した場合はキャッシュを確認します。 オンラインバージョンがキャッシュバージョンよりも高い場合、キャッシュバージョンが更新されます。
   • OnlineOnly fetch オプションの場合、はネットワークのみを照会します。
   • CacheOnly fetch オプションでは、キャッシュのみを確認します。

   olp::dataservice::read::VersionedLayerClient layer_client (
                       client::HRN catalog,
                       std::string layer_id,
                       boost::optional<int64_t> catalog_version,
                       client::OlpClientSettings settings);
   

3. DataRequest パーティション ID と次のいずれかのフェッチオプションを使用してオブジェクトを作成します。

   • ( デフォルト ) 要求されたリソースがキャッシュに見つからない場合にネットワークを照会するに OnlineIfNotFoundは、を使用します。
   • キャッシュの検索をスキップして、ただちにネットワークにクエリーを送信するに OnlineOnlyは、を使用します。
   • キャッシュの検索に失敗した場合にただちに戻るに CacheOnlyは、を使用します。

   auto request = olp::dataservice::read::DataRequest()
                      .WithPartitionId(partition_id)
                      .WithBillingTag("MyBillingTag")
                      .WithFetchOption(FetchOptions::OnlineIfNotFound);
   

4. GetRequestDataRequest パラメーターを使用してメソッドを呼び出します。

   auto future = layer_client.GetData(request);
   

5. DataResponse 未来を待っていてください。

   olp::dataservice::read::DataResponse data_response =
   future.GetFuture().get();
   

DataResponse このオブジェクトは、完了した操作の詳細を保持し、操作の成功および結果のデータへのアクセスを判断するために使用されます。

• IsSuccessful() –操作が成功した場合は、を返し trueます。 それ以外の場合は、を返します false
• GetResult()–操作が成功すると、次の結果データが返されます。 olp::dataservice::read::DataResult
• GetError() – olp::client::ApiError オブジェクトのエラーの結果としてエラー情報が含まれます。

if (data_response.IsSuccessful()) {
    auto response_result = data_response.GetResult();
    // Handle success
} else {
    auto api_error = data_response.GetError();
    // Handle fail
}

DataResult このクラスには、のエイリアスである生のパーティション データが含ま std::shared_ptr<std::vector<unsigned char>>れています。