カタログを作成します

HERE platform に提供するデータがある場合は、データを格納するカタログを作成する必要があります。 カタログは、論理的に単一のセットとして管理されるデータのコレクションです。 カタログには、相互に変化し、相互に依存するレイヤーを含めることができます。 たとえば、道路の属性、トポロジ、および標識のレイヤーを含むマップがカタログに含まれている場合があります。

このトピックでは、 REST サービスconfigv1を使用してカタログを作成する方法の概要を示します。 config サービスの使用方法の詳細については 、『 API リファレンス』を参照してください。

（任意）地域のデータストレージを選択します

config API リクエストを使用して単一のリージョンおよび複数リージョンのカタログを作成するときにデータが保存されるリージョンを選択するか、またはカタログを作成するときに [新しいカタログを追加] インターフェイスの [データの保存先を選択] フィールドを使用して選択できます。

より近いリージョンを選択すると、そのリージョンでのデータの書き込みおよび読み取り時のリージョン間の遅延を軽減できます。 複数リージョンのカタログを作成するときに、バックアップリージョンを選択することもできます。

データストレージのリージョンを選択する場合、次の制限があります。

• データが保存されている地域の選択は、現在、米国西部および EU 西部地域に限定されています。 US West リージョンでは、現在次のレイヤタイプがサポートされています。
  • ストリーム レイヤー
  • バージョン管理されたレイヤー
  • 揮発性レイヤー
• 地域データストレージの選択は、新しく作成されたカタログにのみ利用でき、既存のカタログには適用できません。
• カタログの作成中に選択した領域は、カタログの作成後に変更できません。 この設定を変更するには、カタログを削除してから再作成する必要があります。

( オプション ) データの耐久性を高めるための複数リージョンの複製

複数リージョン機能を選択するに は、config API リクエストを使用するか、またはカタログ作成時に [新しいカタログを追加] インターフェイスの [バックアップリージョンにデータを複製] チェックボックスをオンにします。 複数リージョンのカタログを作成すると、プラットフォーム が必要なすべてのタスクを自動的に実行して、進行中のデータの変更をバックアップリージョンに伝播します。

地域がダウンした場合、データはバックアップリージョン経由で利用できますが、データリクエストの送信元に応じて、より高い遅延が予想されます。

複数リージョンのレプリケーションを有効にすると、追加のストレージ容量とデータ I/O が請求されます。

• ストレージの使用料（ Blob 、 Volatile 、ストリーム 、ストリーム TTL 、メタデータ ）は、バックアップリージョン内のデータの保存量を反映するために 2 倍になります。
• アップロードするオブジェクトのサイズに応じて、転送料金 ( データ IO) が 2.5 ～ 4 倍増加します。大きいオブジェクトの数が少ないほど、小さいオブジェクトの数が多いほど増加します。

現在、複数リージョンの複製は、次のレイヤタイプおよび操作でサポートされています。

• バージョン管理されたレイヤーに対する読み取りと書き込みを行います。
• 揮発性レイヤーに対する読み取りと書き込みを行います。
• ストリームレイヤーに対する読み取りと書き込み。

現在サポートされているのは、バージョン管理、揮発性、およびストリーム レイヤー の各操作のみであるため、複数リージョンのカタログには、バージョン管理、揮発性、およびストリーム の各レイヤーのみを追加できます。

さまざまなレイヤータイプでサポートされているさまざまな使用例により、整合性の保証とデータ複製の戦略が異なります。

• バージョニングレイヤーの場合 :

  • HERE Workspace では、同期データ複製プロセスが使用されます。 このレプリケーションプロセスは、選択した領域とバックアップ領域の両方に正常に書き込まれた場合にのみデータが確認される読み取り / 書き込み後の整合性に準拠します。 同期複製プロセスでは、選択したリージョンとバックアップリージョンの両方が使用可能な場合にのみ、バージョン管理されたレイヤーへの書き込みが可能になります。 リージョンのフェールオーバーイベント中は、リージョンのダウン中に新しいデータを書き込むことはできません。 インシデントよりも前にすでに書き込まれているすべてのデータは、いずれの地域でも読み取ることができます。
  • プラットフォーム がバックアップ領域にデータをコピーする場合、レーテンシーが追加されます。これもデータのサイズの影響を受けます。

• 揮発性レイヤーの場合 :

  • HERE Workspace では、データを別のリージョンに非同期でコピーすることで、最終的な整合性を保証できます。 データは地域に書き込まれると確認応答され、接続が存在する限りバックアップ地域に書き込まれます。 リージョンがダウンしているときにプラットフォーム がバックアップリージョンに書き込むことができない場合、データが失われます。
  • ボラタイル レイヤー データ冗長性の詳細については、「ボラタイル レイヤー 設定」を参照してください。
  • レプリケーションプロセスは書き込みレーテンシーに悪影響を与えることはありませんが、インターネット接続およびデータのサイズによっては、バックアップ領域にデータが表示されるまでに遅延（レプリケーション時間）が生じることがあります。

• ストリーム レイヤーの場合 :
  • データがバックアップリージョンに書き込まれ、リージョンで確認応答されると、データがバックアップリージョンに非同期で複製されます。 リージョンに書き込まれたデータのうち、リージョンのインシデント / フェールオーバーイベントの前にまだバックアップリージョンに複製されていないデータは、リージョンが復旧すると配信されます。 フェールオーバーイベント後に書き込まれた新しいデータは、新しいリージョンとしてバックアップリージョンに書き込まれます。
  • レプリケーションプロセスは書き込みレーテンシーに悪影響を与えることはありませんが、スループット、他のリージョンへの接続、データのサイズに応じてレプリケーション時間が異なります。

複数リージョンの複製を有効にするには、カタログの作成時に複製リージョンを指定する必要があります。 この複数リージョンの設定は変更できません。したがって、カタログが複数リージョンのカタログとして作成された後は、単一リージョンのカタログに変更することはできません。

レプリケーションリージョンを指定するに config は、カタログの作成時に API リクエストのペイロードでレプリケーションブロックを使用します。 config サービスの使用方法の詳細については 、『 API リファレンス』を参照してください。

複数リージョンのカタログを作成したら、 API クエリ パラメーターサービスにリージョン API を指定することで、各リージョンのカタログの ベースの URL を取得できます。

カタログを作成します

カタログに含めるレイヤーの種類を決定すると、カタログを作成できます。

カタログを作成するには、次の手順を実行します。

1. OAuth トークン を取得します。 手順については、『Identity & Access Management Guide』を参照してください。
2. API ルックアップサービスを使用して、configv1 API の API エンドポイントを取得します。 手順については 、『 API Lookup 開発者ガイド』を参照してください。
3. config API に対するこのリクエストを使用して、カタログを作成します。 このリクエストでは、 1 つの新しいレイヤーを含むカタログが作成されますが、必要に応じて複数のレイヤーを作成できます。 通常は、カタログを作成するのと同じリクエストで新しいレイヤーを作成しますが、レイヤーのないカタログを作成して、レイヤーを個別に作成することもできます。

  POST /<Base path for the config API from the API Lookup Service>/catalogs HTTP/1.1
  Host: <Hostname for the config API from the API Lookup Service>
  Content-Type: application/json
  Authorization: Bearer <Authorization Token>
  Cache-Control: no-cache
  {
    "description": "<Describe the content and purpose of the catalog>",
    "id": "<A unique identifier>",
    "name": "<Catalog name>",
    "notifications": {
    "enabled": false
    },
    "summary": "<A short description of the content and purpose of the catalog>",
    "layers": [
      {
        "id": "<A unique ID for the layer>",
        "name": "<A user-friendly name to use for display purposes>",
        "summary": "<A short description of the content and purpose of the layer>",
        "description": "<A long description of the content and purpose of the layer>",
        "schema": {
            "hrn": "<The schema's HERE Resource Name>"
        },
        "contentType": "<The media type>",
        "contentEncoding": "<Whether to compress data>",
        "partitioning": {
          "scheme": "<The method to use to divide data in the layer into partitions>",
        },
        "layerType": "<The type of layer: versioned, volatile, or stream>",
        "volume": {
          "volumeType": "durable",
          "maxMemoryPolicy": "failOnWrite"
        }
      }
    ]
  }

揮発性レイヤーおよびストリームレイヤーの設定を指定できます。 バージョン管理されたレイヤーには設定がありません。 詳細については、以下を参照してください。

• ストリーム レイヤー の設定を行います
• バージョン付レイヤー の設定を行います
• ボラタイル レイヤー の設定を行います
• インデックス レイヤー の設定を行います
• オブジェクト ストア レイヤー の設定を行います

• インタラクティブなマップ レイヤー 設定を行います

  応答エレメント href には、カタログ作成プロセスのステータスを取得できる URL が含まれています。 例 :

  {
  "title": "Catalog Creation",
  "href": "https://config.data.api.platform.here.com/config/v1/status/da167243-13cd-1312-1b72-2z5d2dea7460",
  "type": "urn:olp-types:status"
  }
  

  URL は、カタログの作成中にステータスを返します。 例 :

  {
  "status": "pending"
  }
  

  すでに存在する ID を使用してカタログを作成しようとする 409 Conflict と、応答が返されます。

カタログが作成されると、 URL はカタログおよびレイヤーメタデータを返します。

{
    "id": "<The identifier you specified in the create request>",
    "hrn": "<The HERE Resource Name of the catalog>",
    "name": "<The catalog name you specified in the request>",
    "summary": "<The summary you specified in the request>",
    "description": "<The description you specified in the request>",
    "owner": {
        "creator": {
            "id": "<The App ID associated with the credentials used in the create request> "
        },
        "organisation": {
            "id": "<The realm of the user ID used in the create request>"
        }
    },
    "tags": [],
    "billingTags": [],
    "created": "<The time stamp indicating when the catalog was created>",
    "layers": [
        {
            "id": "<The layer ID>",
            "hrn": "<The HERE Resource Name of the layer>",
            "name": "<The layer name>",
            "summary": "<The summary description of the purpose and content of the layer>",
            "owner": {
                "creator": {
                    "id": "<The App ID used to create the layer>"
                },
                "organisation": {
                    "id": "<The realm in which the layer was created>"
                }
            },
            "partitioningScheme": "<The partitioning scheme of the layer, HEREtile or generic>",
            "partitioning": {
                "tileLevels": [
                    0
                ],
                "scheme": "heretile"
            },
            "contentType": "application/json",
            "contentEncoding": "gzip",
            "volume": {
                "volumeType": "durable"
            },
            "tags": [],
            "billingTags": [],
            "created": "2018-01-29T16:16:55.402Z",
            "layerType": "<The layer type: versioned, volatile, stream, or objectstore>"
        }
    ],
    "version": 0,
    "notifications": {
        "enabled": false
    }
}

このメタデータ、特にレイヤー HRNS を使用すると、データをカタログに公開できます。

カタログの作成例

HERE は、カタログの作成方法の例です。 この例では、 "Example Layer" という名前の 1 つのレイヤーを持つ "My Traffic Catalog" という名前の新しいカタログを使用しています。 これらのレイヤーはバージョン付レイヤーです。

POST /config/v1/catalogs HTTP/1.1
Host: config.data.api.platform.here.com
Content-Type: application/json
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

{
  "description": "This is a test catalog.",
  "id": "my-catalog",
  "name": "My Traffic Catalog",
  "notifications": {
  "enabled": false
  },
  "summary": "This is a test catalog.",
  "layers": [
    {
      "id": "my-layer",
      "name": "Example Layer",
      "summary": "The traffic incident layer contains information about events that are affecting the flow of traffic or that may be important for drivers to know.",
      "description": "This layer provides aggregated information about traffic incidents, including the type and location of each traffic incident, status, start and end time, and other relevant data. This data is useful to dynamically optimize route calculations. It also provides access to real-time traffic flow data in including information on speed and congestion for specific regions.",
      "schema": {
          "hrn": "hrn:example:schema:::traffic-schema"
      },
      "contentType": "application/json",
      "contentEncoding": "",
      "partitioning": {
        "scheme": "heretile"
      },
      "layerType": "versioned",
      "volume": {
        "volumeType": "durable"
      }
    }
  ]
}

curl -X POST https://config.data.api.platform.here.com/config/v1/catalogs \
-H 'Content-Type: application/json' \
-H 'Authorization: Bearer <Authorization Token>' \
-H 'Cache-Control: no-cache' \
-d '{
  "description": "This is a test catalog.",
  "id": "my-catalog",
  "name": "My Traffic Catalog",
  "notifications": {
  "enabled": false
  },
  "summary": "This is a test catalog.",
  "layers": [
    {
      "id": "my-layer",
      "name": "Example Layer",
      "summary": "The traffic incident layer contains information about events that are affecting the flow of traffic or that may be important for drivers to know.",
      "description": "This layer provides aggregated information about traffic incidents, including the type and location of each traffic incident, status, start and end time, and other relevant data. This data is useful to dynamically optimize route calculations. It also provides access to real-time traffic flow data in including information on speed and congestion for specific regions.",
      "schema": {
          "hrn": "hrn:example:schema:::traffic-schema"
      },
      "contentType": "application/json",
      "contentEncoding": "",
      "partitioning": {
        "scheme": "heretile"
      },
      "layerType": "versioned",
      "volume": {
        "volumeType": "durable"
      }
    }
  ]
}'

カタログが作成されると、ステータス URL へのリクエストによって次の内容が返されます。

{
    "id": "my-catalog",
    "hrn": "<Catalog HRN>",
    "name": "My Traffic Catalog",
    "summary": "This is a test catalog.",
    "description": "This is a test catalog.",
    "owner": {
        "creator": {
            "id": "Mejk6DMxAq7kKI5lt2T2"
        },
        "organisation": {
            "id": "olp-here-test"
        }
    },
    "tags": [],
    "billingTags": [],
    "created": "2018-01-29T16:16:55.402Z",
    "layers": [
        {
            "id": "my-layer",
            "hrn": "<Catalog HRN>",
            "name": "Example Layer",
            "summary": "The traffic incident layer contains information about events that are affecting the flow of traffic or that may be important for drivers to know.",
            "description": "This layer provides aggregated information about traffic incidents, including the type and location of each traffic incident, status, start and end time, and other relevant data. This data is useful to dynamically optimize route calculations. It also provides access to real-time traffic flow data in including information on speed and congestion for specific regions.",
            "owner": {
                "creator": {
                    "id": "Mejk09M4Aq71KI5l1t2T2"
                },
                "organisation": {
                    "id": "olp-here-test"
                }
            },
            "partitioningScheme": "heretile",
            "partitioning": {
                "tileLevels": [
                    0
                ],
                "scheme": "heretile"
            },
            "contentType": "application/json",
            "contentEncoding": "gzip",
            "volume": {
                "volumeType": "durable"
            },
            "tags": [],
            "billingTags": [],
            "created": "2018-01-29T16:16:55.402Z",
            "layerType": "versioned"
        }
    ],
    "version": 0,
    "notifications": {
        "enabled": false
    }
}

レイヤータイプを選択します

次の表に、各レイヤータイプの特性の概要を示します。

レイヤータイプの詳細について は、「レイヤー」を参照してください。