ボラタイル レイヤーにデータを公開します

ボラタイル レイヤーにデータを公開するに は、 REST API publish（メタデータの場合）およびvolatile-blob（データの場合）を使用します。

オプションで、データが含まれているすべてのパーティションについてメタデータを保存できます。 クエリの目的でメタデータをアップロードすることをお勧めします。 たとえば metadata 、 API を使用して、データを含むパーティション、または特定のメタデータプロパティを持つデータを含むパーティションを検索できます。 ボラタイル レイヤーにメタデータを含める場合は、データを含むすべての新しいパーティションで公開する必要があります。 通常は、レイヤーにデータを初めて公開するときに行います。 新しいパーティションのデータを公開する場合は、メタデータも含める必要があります。 同様に、パーティション データを削除する場合は、メタデータを削除する必要があります。 すべてのパーティションのメタデータには、 volatile-blob API を使用してデータ自体にアクセスしたり、データを変更したりするために使用するデータ ハンドルが含まれています。 複数のパーティションに同じデータが含まれている場合は、同じデータ ハンドルを使用できます。 メタデータがパーティションにパブリッシュされた後、各データハンドルを使用して、以降のメタデータパブリケーションを必要とせずにデータを繰り返し更新できます。

パーティションのメタデータを公開する一般的なフローは、次の手順で構成されています。

1. 認可トークンを取得します。
2. API ベースの URL を取得します。
3. パブリケーションを初期化します。
4. メタデータを生成します。
5. メタデータをアップロードします。
6. パブリケーションを送信します。
7. パブリケーションが完了するまで待ちます。

パーティションにデータを公開する一般的なフローは、次の手順で構成されています。

1. API ベースの URL を取得します。
2. データをアップロード / 削除します。

メタデータ を公開しています

認可トークン を取得します

HTTP 要求の認可トークンを取得します。 手順について は、『 Identity & Access Management Guide 』を参照してください。

API ベースの URL を取得します

API ルックアップサービスを使用して、公開先のカタログのpublishv2 API のベース URL を取得します。 手順については 、『 API Lookup 開発者ガイド』を参照してください。

パブリケーションを初期化します

パブリケーション ID を要求して、パブリケーションを初期化します。 パブリケーション ID は、ボラタイル レイヤーに作成するメタデータパブリケーションのセットの一意の識別子です。

パブリケーションを初期化するには publish 、 API を使用します。

POST /<Base path for the publish API from the API Lookup Service>/publications HTTP/1.1
Host: <Hostname for the publish API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache

{
 "layerIds": [
   "<Layer to Publish To>"
 ]
}

応答に はパブリケーション ID が含まれます。 例 :

{
    "id": "abc1234567-xy90-11aa-abc123-abc123456789",
    ...
}

メタデータ を生成します

メタデータの生成方法は、パーティションを追加するか削除するかによって異なります。

新しいパーティションのメタデータ を生成します

新しいパーティションのパーティション メタデータは、少なくとも次のもので構成されている必要があります。

• パーティション ID
• データのアップロードおよび利用に使用されるデータ ハンドル

ユーザーは、新しい各パーティションのデータ ハンドルを生成する責任があります。 データ ハンドルは任意のものを選択できますが、いくつかの要件があります。 データ ハンドル：

• 任意の一意の番号、またはコンテンツまたはメタデータのハッシュを指定できます。 ただし、各パーティションに同じデータが含まれている場合、パーティションは同じデータ ハンドルを使用できます。
• ボラタイル レイヤー内で一意であることが必要です。

設定できるメタデータフィールドの詳細な説明については、publish API についての API リファレンス 情報を参照してください。

削除されたパーティションのメタデータ を生成します

削除されたパーティションのパーティション メタデータは、次のもので構成されて

• 削除されたパーティションの空のデータハンドル。 空のデータハンドルを公開すると、削除されたパーティションのメタデータが削除されます。
• 削除された各パーティションのパーティション ID 。

メタデータ をアップロードします

すべてのメタデータが生成および集約された後、メタデータをアップロードします。 Aggregated メタデータには、追加および削除されているすべてのパーティションが含まれます。 削除するパーティションのデータ ハンドルが空になります。 メタデータをアップロードするには publish 、 API を使用します。

POST /<Base path for the publish API from the API Lookup Service>/layers/<Layer ID>/publications/<Publication Id>/partitions HTTP/1.1
Host: <Hostname for the publish API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/json
Cache-Control: no-cache
{ "partitions":
  [
    {
      "dataHandle": "<Data Handle 1>",
      "partition": "<Partition 1>",
      "checksum": "<Checksum>"
    },
    {
      "dataHandle": "<Data Handle 2>",
      "partition": "<Partition 2>",
      "checksum": "<Checksum>"
    },
    {
      "dataHandle": "<Data Handle 3>",
      "partition": "<Partition 3>",
      "checksum": "<Checksum>"
    }
  ]
}

パーティションのメタデータを削除する例 :

メタデータを削除するに publish は、 API を使用してメタデータを公開する場合と同じ手順を実行しますが、削除するパーティションの空のデータハンドルを送信するだけです。 例 :

  POST /<Base path for the publish API from the API Lookup Service>/layers/<Layer ID>/publications/<Publication Id>/partitions HTTP/1.1
  Host: <Hostname for the publish API from the API Lookup Service>
  Authorization: Bearer <Authorization Token>
  Content-Type: application/json
  Cache-Control: no-cache
  {
    "partitions": [
      {
        "partition": "partition01"
        "dataHandle": ""
      }
     ]
  }

パーティションは、 1 つのパブリケーションで削除および追加できます。

パブリケーションを送信します

すべてのメタデータがアップロードされたら、メタデータがアップロードされたことを示すためにパブリケーションを送信する必要があります。 推奨されるベストプラクティスは、パブリケーションを送信することです。 さらに、廃止された metadata API の使用をサポートしてバージョンごとに揮発性メタデータを取得するには、パブリケーションの送信が必要です。

パブリケーションを送信するには publish 、 API を使用します。

PUT /<Base path for the publish API from the API Lookup Service>/publications/abc1234567-xy90-11aa-abc123-abc123456789 HTTP/1.1
Host: <Hostname for the publish API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Cache-Control: no-cache

パブリケーションが送信されると、 HERE platform がそのパブリケーションを処理します。 現在のパブリケーションの量およびパブリケーションのサイズによっては、処理に数分から数時間かかることがあります。 publish API を使用して、パブリケーションのステータスを確認できます。

  GET /<Base path for the publish API from the API Lookup Service>/publications/<Publication Id> HTTP/1.1
  Host: <Hostname for the publish API from the API Lookup Service>
  Authorization: Bearer <Authorization Token>
  Cache-Control: no-cache

publish v2 の場合、完了したパブリケーションの応答は HTTP ステータス 200 OK を返し、応答本文のstateフィールドに値succeededが含まれます。 例 :

  {
    "layerDetails": [],
    "catalogVersion": 394,
    "id": "v2-1ca3aee1-1c3f-4a98-8288-ecfed7466133",
    "catalogId": "my-catalog",
    "details": {
        "expires": 1526769797871,
        "state": "succeeded",
        "modified": 1526510600520,
        "message": "Publication has succeeded",
        "started": 1526510597871
    },
    "layerIds": [
        "versioned-layer"
    ],
    "type": "partition",
    "versionDependencies": [
        {
            "hrn": "hrn:my-company:data:::my-catalog",
            "version": 395,
            "direct": true
        }
    ]
  }

完了を待っていることは、以前にファイナライズされたパブリケーションが完了するまで新しいパブリケーションを開始できないため、バージョン管理されたパブリケーションプロセスの重要な部分です。 新しいパブリケーションを開始しようとすると、 HTTP 409 の競合応答が発生します。

データを公開しています

API ベースの URL を取得します

API ルックアップサービスを使用 volatile-blob して、公開先のカタログの API のベース URL を取得します。 手順については 、『 API Lookup 開発者ガイド』を参照してください。

データをアップロード / 削除します

メタデータの公開が完了したら volatile-blob 、 API を使用してデータのアップロードを開始できます。 アップロードするデータをリクエスト本文に入力します。 特定のデータ ハンドルのデータがアップロードされるたびに、既存のデータが更新されたデータで上書きされます。

同じメタデータパブリケーションを使用して、データを何度もアップロードできます。 ただし、次の場合は、新しいメタデータの公開が必要です。

• データパーティションのセットが変更されました ( カバレッジの変更が原因である可能性があります ) 。
• パーティションチェックサムを含めています。 publish 更新されたパーティションチェックサムを指定するには、 API を使用する必要があります。

更新するパーティションのデータ ハンドルを把握している必要があります。 メタデータを更新せずに、既存のデータハンドルを使用して、初期化済みパーティション（メタデータを持つパーティション）のデータをアップロードおよび再アップロードできます。

PUT /<Base path for the volatile-blob API from the API Lookup Service>/layers/<Layer ID>/data/<Data Handle> HTTP/1.1
Host: <Hostname for the volatile-blob API from the API Lookup Service>
Authorization: Bearer <Authorization Token>
Content-Type: application/octet-stream
Cache-Control: no-cache

<Data to Upload>

パーティション内のデータを削除する場合は、データ ハンドルが必要です。 データ自体の前にメタデータを削除する場合は、データ ハンドルを削除しないでください。