More than 1 year has passed since last update.

Sync Gateway機能解説：拡張属性（XATTRS）の利用

Posted at 2021-11-25

はじめに

Sync Gatewayで拡張属性を使用する理由

XATTRSは、ドキュメントのルーティングとアクセス制御に使用されるデータをドキュメント内に安全に保持するために使用できます。保持された情報を、Sync関数内で利用することにより、データを使用してアクセス許可を駆動できます。このアプローチには、次の利点があります。

追加レベルのセキュリティを提供する。例えば、チャネルを追加し、ユーザーに対するドキュメントのアクセスコントロールを行う。
情報はメタデータに含まれているため、ドキュメントのコンテンツから分離される。
拡張属性の更新は、新しいリビジョンを作成しない。そのため、アクセス制御情報のみを変更し、ドキュメント全体をクライアントにプッシュする必要性がない。

Sync Gatewayは、この目的のために単一のユーザー定義可能な拡張属性user_xattr_keyを持ちます。

Couchbase Serverの拡張属性についての復習

Couchbase Serverでは、拡張属性（XATTR）を使って、開発者は、アプリケーション固有のメタデータを定義できます。このメタデータは、その存在を把握した上で、明示的にリクエスト、または変更を行おうとするアプリケーションにのみ表示されます。
たとえば、プログラミングフレームワークに固有のメタデータとして利用し、他のアプリケーションやフレームワーク、ないし同じフレームワークの別のバージョンに対して非表示にするということが考えられます。
拡張属性（XATTR）は、基本的に一般的なアプリケーションでの使用を目的としておらず、ライブラリーやフレームワークで利用することが想定されています。

拡張属性（XATTR）に保存されているデータには、通常のCouchbase Serverのデータへアクセスする方法では、簡単にアクセスできないようになっています。
Couchbase Server SDKは、サブドキュメントAPIの拡張機能によって拡張属性をサポートしていおり、拡張属性の定義、検索、編集、削除などを行うことができます。ただし、サブドキュメント操作を通常の属性ではなく拡張属性で実行するように指定するには、アプリケーションでxattrフラグをtrueに設定する必要があります。

Couchbase Serverに保存されているドキュメントの最大サイズは20MBであり、拡張属性（XATTR）は、ユーザー利用領域としてこのコンテンツサイズを消費します。

Sync Gatewayで拡張属性を利用する方法

構成

Sync Gatewayは、構成プロパティの一部として、ユーザー定義による拡張属性の名前user_xattr_keyを持ちます。

拡張属性（XATTR）は、値として、文字列、配列、オブジェクトなど、JSONとして有効な要素を取ることができます。

次の例では、Admin REST APIを使用して、データベースhotelsに、XATTR名「channelXattr」を指定しています。

curl -X PUT 'http://localhost:4985/hotels/_config' \
--header 'Accept: application/json' \
--header 'Content-Type: application/json' \
--data-raw '{
    "user_xattr_key": "channelXattr" 
    }
}'

ここで、「channelXattr」が、チャネルルーティング情報を保持するように指定された拡張属性の名前として設定されます。

設定

Couchbase Server SDK APIを使用して、XATTRの値を設定および維持できます。Sync Gateway REST APIを使用して設定することはできません。ドキュメントの作成時および更新時に、SDK APIを使用してxattrの値を設定します。

Couchbase Serverドキュメントのメタデータの例について、以下示します。

{
  "meta": { ①
    "id": "1000",
    "rev": "7-1680c88cbce700000000000002000006",
    "expiration": 0,
    "flags": 33554438,
    "type": "json"
  },
  "xattrs": { ②
    "channelXattr": [ ③
      "channel1",
      "channel3",
      "useradmin"
    ]
  }
}

① システムメタデータ
② ユーザーメタデータとしての拡張属性
③ ここで、channelXattrは、Sync関数に渡されるチャネルルーティング情報を保持する指定されたxattrの名前です。値は、ドキュメントの作成時および更新時に、SDK APIを使用して設定されたものです。

利用

Sync Gateway構成プロパティuser_xattr_keyで指定された拡張属性（XATTR）は、Sync関数の引数metaを使って、meta.xattrs.<拡張属性名>の形で、利用できます

function (doc, oldDoc, meta) { ①

  if (meta.xattrs.channelXattr == "undefined") ②
    {
      console.log("no user_xattr_key defined")
      channel(null)
    } else {
      channel(meta.xattrs.channelXattr) ③
    }

  // Further processing as required ../

① sync関数の引数に、metaを含めます。
② metaオブジェクトにアクセスして、対象の拡張属性がこのドキュメントに存在することを確認します。
③ 拡張属性のコンテンツを使用し、チャネルを定義します。

Sync Gateway機能解説：拡張属性（XATTRS）の利用

はじめに

Sync Gatewayで拡張属性を使用する理由

Couchbase Serverの拡張属性についての復習

Sync Gatewayで拡張属性を利用する方法

構成

設定

利用

関連情報