Additional resources

データサービス API (ベータ版)


バージョン 1.0

データサービスとは?

データサービスを使用することで、あらゆる種類のデータを Lucid (chart/press) に取り込んで視覚化することができます。簡単な REST API でデータへの変更をほぼリアルタイムで文書に反映させることができます。API に加え、データサービスでは、.csv、.xlsx、Google Sheets などの表形式のデータを取り込むのに役立つ便利なアダプターも提供しています。データサービスにより、以下が容易になります。

  • インテグレーションまたは API 経由での Lucid(chart/press) への手動でのデータセットのアップロード
  • Lucid の共通形式に合わせたデータセットの処理
  • 保存されたデータソースの手動または自動更新
  • 文書で使用する特定のデータのクエリと取得
  • 保存されているデータソースへのアクセスの管理と共有
  • 外部データソースによる認証

データサービスを使用することで、Lucid (chart/press) のユーザーは、Lucid プラットフォームの特長であるリアルタイムのコラボレーションときめ細かいアクセス制御機能を犠牲にすることなく、文書に柔軟にデータを追加することができます。

API の使用方法

認証

データサービスへのリクエストはすべて、有効なユーザー資格情報で認証される必要があります。Lucid は OAuth 1.0 認証をサポートしています。まずこちらのリンクを使用して開始します。

バージョン管理

データサービスへのリクエストには、リクエストヘッダーの一部としてバージョン番号をそれぞれ指定する必要があります。指定されたバージョン番号は、クライアントが想定するデータサービス API のバージョンを示します。現在利用可能な最新バージョンは、バージョン1のみです。バージョン管理を追加するには、HTTP リクエストに以下の形式の Accept ヘッダーを含める必要があります : 'Accept': 'application/json;v=1'

レート制限

データサービスの不正使用や過大な負荷を防ぐため、API にはユーザーのリクエストを制限するレート制限機能 (別名スロットリング) があります。

Lucid では、このレート制限エラーを適切に処理するようインテグレーションを設計することをおすすめします。そのためには、このエラーが発生した際にインテグレーションが60秒間スリープし、その後リクエストを再試行するよう設定することができます。もしくは、エラー処理戦略として指数バックオフを実装し、再試行間の待機時間を徐々に長くしながら、リクエストが成功するか特定の再試行回数に達するまで失敗したリクエストを定期的に再試行することもできます。

 

フリー

スタンダード

エンタープライズ

ハードリフレッシュの間隔

なし

最後の試行から60秒

最後の試行から30秒

ソフトリフレッシュの間隔

なし

最後の試行から60秒

最後の試行から30秒

ユーザー API レート

リクエスト200件/分

リクエスト200件/分

リクエスト500件/分

アカウント API レート

リクエスト0件/分

リクエスト0件/分

リクエスト0件/分

ファイルサイズ制限

2 MB

2 MB

2 MB

アダプターの種類

CSV
Excel
Google Sheets
BambooHR
AWS

CSV
Excel
Google Sheets
BambooHR
AWS

すべて

現在のレート制限を確認する方法 :

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/rateLimits

URI の例 : https://data.app.lucidchart.com/rateLimits

戻り値 :

{
    userHardRefreshInterval: <Number>,
    userSoftRefreshInterval: <Number>,
    userApiCallRate: <Number>,
    accountApiCallRate: <Number>,
    fileSizeLimit: <Number>,
    adapterTypes = [<String>...]
}

データサービスの仕組み

図 A: スプレッドシートファイル (Excel ファイルや Google Sheets に類似) の概念とデータサービス構造の比較

データセット

データセットとは、データソースの論理的なグループを指し、関連するスプレッドシートのグループとして捉えることができます。データセットには複数の関連データソースを含めることができますが、1つのデータソースが属することができるデータセットは最大で1つです。

データセット許可

各データセットには、1つ以上のデータセット許可を関連付ける必要があります。データセット許可の目的は、データセットの認可レベルを指定することにあります。データセット許可はそれぞれ、アクセスレベル、認可タイプ、その認可が属するユーザー、アカウントや文書を示す識別子文字列で構成されます。アクセスレベルには、編集と表示の2種類があります。認可タイプには、ユーザー、アカウント、文書の3種類があります。

  • "user": このレベルは、個別のユーザーの Lucid id が許可の識別子文字列に等しい場合にそのユーザーにアクセス権限を付与します。
  • "account": このレベルは、許可の識別子文字列で指定されたエンタープライズ/チームアカウントのユーザー全員にアクセス権限を付与します。
  • "document": このレベルは、許可の値で参照される Lucid (chart/press) 文書へのアクセスが可能なすべてのユーザー (関連する Lucid (chart/press) のエンタープライズ/チームアカウントのユーザーでない場合でも) にアクセス権限を付与します。特定の文書に対してユーザーがもつアクセス権限の種類は、その文書経由でデータセット許可により付与されるアクセス権限に影響を及ぼしますので注意してください。とりわけ、あるユーザーが特定の文書に関して読み取り専用の権限をもつ場合にこの文書経由でデータセット許可を付与すると、データセット許可自体にリストされたアクセスレベルとは関係なく、これらのユーザーには最大で「閲覧」レベルのアクセスが付与されます。

データソース

データソースはコレクションで構成され、Excel ファイルや Google Sheetsドキュメントのように構造化されたスプレッドシートファイルとして捉えることができます。データソースは最大で1つのデータセットに属することができますが、データセットに属さずに存在することもできます。

ソース許可の取得

各データソースには、1つ以上のデータソース許可を関連付ける必要があります。データソース許可の目的は、ユーザーがアクセスしようとしているデータソースの認可レベルを指定することにあります。データソース許可はそれぞれ、アクセスレベル、認可タイプ、その認可が属するユーザー、アカウントや文書を示す識別子文字列で構成されます。アクセスレベルには、edit と view の2種類があります。認可タイプには、ユーザー、アカウント、文書の3種類があります。

  • "user": このレベルは、個別のユーザーの Lucid id が許可の識別子文字列に等しい場合にそのユーザーにアクセス権限を付与します。
  • "account": このレベルは、許可の識別子文字列で指定されたエンタープライズ/チームアカウントのユーザー全員にアクセス権限を付与します。
  • "document": このレベルは、許可の値で参照される文書へのアクセスが可能なすべてのユーザー (関連する Lucid (chart/press) のエンタープライズ/チームアカウントのユーザーでない場合でも) にアクセス権限を付与します。特定の文書に対してユーザーがもつアクセス権限の種類は、その文書経由でソース許可により付与されるアクセス権限に影響を及ぼしますので注意してください。とりわけ、あるユーザーが特定の文書に関して読み取り専用の権限をもつ場合にこの文書経由でソース許可を付与すると、ソース許可自体にリストされたアクセスレベルとは関係なく、これらのユーザーには最大で「閲覧」レベルのアクセスが付与されます。

シナリオ例1: 

Bob は Google Sheets ドキュメントをデータサービスにアップロードし、データソースを Lucidchart 文書に添付し、その Lucidchart 文書を同じ Lucidchart アカウントを使用している同僚 (Alice) と共有します。Alice は、Lucidchart 文書にすでに保存されているデータに加え、Bob がそのデータに対して行う変更や更新を閲覧することができますが、データを自分で更新することはできません。次に、Bob は自分のデータソースに対して新たに "account" レベルのソース許可を作成します。Alice と Bob は同じ法人アカウントを使用する同僚であるため、Alice は Lucidchart 文書のデータを更新でき、Google Sheets ドキュメントの更新内容も確認できるようになりました。"account" レベルのソース許可を追加することで、Bob と同じ法人アカウントをを使用する Alice は Lucidchart 文書のデータを更新できるようになったのです。 

シナリオ例2: 

Bob は Google Sheets ドキュメントをデータサービスにアップロードし、データソースを文書に添付し、その文書をコンサルタントの Carol と共有します。Carol は Bob と同じ Lucidchart アカウントに属していません。Carol は、Lucidchart 文書にすでに保存されているデータを閲覧することができますが、そのデータの更新や Google Sheets ドキュメントに加えられた変更の確認はできません。Bob が新たに "document" レベルのソース許可を作成すると、Carol は Lucidchart 文書のデータを更新でき、Google Sheets ドキュメントの更新内容も確認できるようになりました。

コレクション

コレクションとは、データソース内のコンテナーを指します。データソースは多数のコレクションを含むことができますが、コレクションが属することができるデータソースは1つのみです。コレクションは、スプレッドシートファイル内のタブや個別のシートとして捉えることができます (図 A 参照)。CSV ファイルの場合、コレクションは1つのみとなります。コレクションにはそれぞれ、スキーマアイテムコレクションプロパティメタデータコレクションが含まれます。

アイテム

アイテムとは、コレクション内のコンテナーを指し、スプレッドシート内の1つの行として捉えることができます (図 A 参照)。コレクションは多数のアイテムを含むことができますが、アイテムが属することができるコレクションは1つのみです。各アイテムはフィールドで構成されます。

フィールド

フィールドにはそれぞれ値があり、スプレッドシート内の1つのセルとして捉えることができます (図 A 参照)。アイテムは多数のフィールドを含むことができますが、フィールドが属することができるアイテムは1つのみです。

スキーマ

コレクションにはそれぞれ、そのコレクションの内容を記述するスキーマが1つあります。スキーマは、スプレッドシートのヘッダー行として捉えることができます (図 A 参照)。スキーマはフィールド定義で構成されます。

フィールド定義

フィールド定義はそれぞれ、フィールドの名前と型 (文字列、数値、ブール型など) を記述します (図 A参照)。また、フィールドが主キーであるかどうか、主キーである場合は主キーの順序、さらにフィールドの既定値も指定します。フィールドの名前は、スプレッドシートの列の名前と捉えることができます。

主キーは、所属するアイテムの識別子として機能します。アイテムのフィールド値が指定されていない場合は、フィールド定義の既定値が使用されます。

例えば、以下のスニペットをスプレッドシートからデータサービスに保存するとします。

 

名前

社会保障番号

18歳以上

1

Bob 

123456789

2

Alice

234567890

3

Carol

098765432

このスキーマでは、各列に1つずつ、3つのフィールド定義があります。最初のフィールド定義の名前は "名前" となり、その型は "文字列" となります。この場合の一意の識別子は "社会保障番号" となるため、"名前" フィールドは主キーになりません。2番目のフィールド定義の名前は "社会保障番号" となり、その型は "数値" となります。これは、各アイテムの識別に使用できる一意の値であるため、主キーとなります。3番目のフィールド定義の名前は "18歳以上" となり、型は "ブール型" となり、

データセットプロパティ

データセットは、データセット全体を記述できるプロパティをもつことができます。データセットプロパティは、データセットのコンシューマーが使用できる情報のキー値ストアです。データセットプロパティはコレクションプロパティと非常によく似ています。

コレクションプロパティ

コレクションは、コレクション全体を記述できるコレクションプロパティをもつことができます。これらのプロパティの一部は事前定義されています。つまり、データサービスまたは Lucidchart/press クライアントのいずれかが、Lucid によってあらかじめ決定された方法でプロパティを自動で読み取り、解釈します。ただし、データ API 自体が作成または使用できるプロパティを制限することはなく、サードパーティ製のアプリケーションは、未使用の任意のプロパティを使用してコレクションにタグを付けることができます。コレクションのプロパティはコレクションプロパティエンドポイントを使用して変更することができます。

Lucidchart と Lucidpress のユーザーに役立つプロパティ :

DefaultColor

  • このプロパティは、すべてのセルのデフォルトの塗りつぶし色を定義します。FillColor メタデータコレクションを変更またはエントリーを追加することで上書きできます。

DefaultTextColor

  • このプロパティは、すべてのセルのデフォルトのテキスト色を定義します。TextColor メタデータコレクションにエントリーを追加することで上書きできます。

headerRow

  • このプロパティは、コレクションのスキーマの構築に使用する行番号を定義します。

InheritsSchemaChanges

  • このプロパティがメタデータコレクションで文字列 "true" に設定されている場合、親コレクションのスキーマに対する変更の一部がメタデータコレクションに自動で反映されます。詳細はメタデータコレクションを参照してください。

メタデータコレクション

コレクションは、メタデータコレクションをもつことができます。メタデータコレクションが属するコレクションは、親コレクションと呼ばれます。メタデータコレクションは、親コレクションに関するプロパティや情報で、元のコレクションの表形式の構造には馴染みにくいものの、論理的には親コレクションが示す同じトップレベルの「ファイル」の一部であるものを保持します。コレクションプロパティとは異なり、メタデータコレクションは非常に大きくなる場合もあり、親コレクションの特定のセルを変更する情報を保持することができます。 

API に関しては、メタデータコレクションは主に標準コレクションのように動作します。トップレベルコレクションとメタデータコレクションの主な相違点は次のとおりです。

  1. すべてのコレクションの取得すべてのコレクション数の取得エンドポイントにはメタデータコレクションが含まれません。これは、メタデータコレクションが論理的に親の一部であるためです。
  2. 特定のコレクションのすべてのメタデータコレクションをコレクション JSON オブジェクトメタデータフィールドで確認することができます。
  3. メタデータコレクションに対する変更は、自動的に親コレクションに対する変更として扱われます。特に、メタデータコレクションの変更に対応して親コレクション コレクション JSON オブジェクトversionTimestamp フィールドが更新されます。親コレクションに対する変更に対応するものはすべて、メタデータコレクションに対する変更にも対応します。
  4. InheritsSchemaChanges プロパティを "true" の値でメタデータコレクションに含めると、親コレクションのスキーマに対する変更の一部がメタデータコレクションに継承されます。スキーマの変更を継承するメタデータコレクションを参照してください。

Lucid の Excel/Google Sheets アダプターにより自動生成されるメタデータコレクションの大半は、親データに対してセルごとにメタデータを記述します。例えば、以下のスニペットを Google Sheets スプレッドシートからデータサービスに再作成するとします。

 

A

B

1

2

このスプレッドシートは、2つの行と "A" と"B" の2つのフィールドをもつコレクションとして表され、"A" と "B" はスキーマで定義されています。コレクションには、"DefaultColor":"ffffff" を指定するコレクションプロパティが含まれ、さらに型が "FillColor" のメタデータコレクションも含まれます。FillColor メタデータコレクションのアイテムは以下のようになります。

{ 
    "row":"1",
    "A": "#FF0000",
    "B": "#00FF00"
},
{ 
    "row":"2",
    "A": "#0000FF"
}

 

行 2/フィールド B は定義されていないため、クライアントはコレクションプロパティで示される既定の色に戻ります。また、"row" 列の追加により、メタデータコレクションのスキーマは元のコレクションとは異なるものとなります。

 

ユーザーは、以下に詳述するメタデータ以外の独自のメタデータコレクションを自由に定義できます。

Google Sheets と Excel メタデータコレクション

Google Sheets または Excel アダプターを使用して作成されたコレクションには、最大6つのメタデータコレクション (FillColor、TextColor、Format、Comment、Formula、SheetOrder) が含まれます。これらの各コレクション (SheetOrder 以外) に関しては、親コレクションのスキーマに加えられた変更がメタデータコレクションのスキーマに反映されます (スキーマの変更を継承するメタデータコレクションを参照してください)。これらのメタデータコレクション内の各アイテムは、親コレクション内の1つの行を参照します。列を参照する 'fields' オブジェクトのプロパティは、単一のセルを参照するために使用することができます。例えば、プロパティが "row": "5" かつ "C": "12" のアイテムは、行5/列C のセルを "12" の値で上書きします。

塗りつぶしの色

  • セルの塗りつぶしの色の上書きを格納するメタデータコレクション。セルがこのコレクションで定義されていない場合、既定値は DefaultColor になります。 
  • アイテムの例 : 
{
"row": "6",
"A": "fffffff",
"C": "dd7e6bff"
}

 

テキストの色

 

  • セルのテキストの色の上書きを格納するメタデータコレクション。セルがこのコレクションで定義されていない場合、既定値は DefaultTextColor になります。 
  • メタデータコレクションアイテムの例 (行 5、列 A-C のテキストの色を上書き) :
{
"row": "5",
"A": "fce5cdff",
"B": "000000ff",
"C": "000000ff"
}

 

フォーマット

 

  • Google Sheets のテキスト書式設定ドキュメンテーションに定めるテキスト書式規則に従いセルの文字列を設定するメタデータコレクション。この書式は Google Sheets のものとは若干異なり、Lucid の書式では情報がコロンで2つに区切られています。最初の部分は、使用する NumberFormatType を指定する整数 (リストされた型の順に 0~8) です。2番目の部分は、指定された文字列に適用される書式設定情報です。これらの値は、Google Sheets または Excel アダプターを使用してインポートすると自動生成されますが、メタデータコレクションを直接編集する場合には指定が必要となります。
  • メタデータコレクションアイテムの例 (行 8、列 B を上書きして日付形式を使用し、行 8、列 B を上書きして米国通貨形式を使用) :
{
"row": "8",
"B": "5:M/d/yyyy",
"C": "4:\"$\"#,##0.00"
},

 

数式

 

  • セルを上書きするメタデータコレクションで、数式を使用して周囲のセルから値を計算します。
  • メタデータコレクションアイテムの例 (行 10、列 C を上書きして C2:C9 の合計を取得) :
{
"row": "10",
"C": "=SUM(C2:C9)"
}

 

コメント

 

  • セルに関連付けられた Excel 'Comments' または Google Sheets 'Notes' を格納するメタデータコレクション。
  • メタデータコレクションアイテムの例 (行 4、列 C にコメントを追加) :
{
"row": "4",
"C": "Example Comment"
}

 

SheetOrder

 

  • シートで使用される行の順序を指定するメタデータコレクション。このコレクションのスキーマは親スキーマと一致しないため、親スキーマに対する変更はこのコレクションには反映されません。
  • メタデータコレクションアイテムの例 (id 111 の行を行の順序の 2 番目に設定) :
{
"id": "111",
"row": "2"
},

スキーマの変更を継承するメタデータコレクション

プロパティ InheritsSchemaChanges が "true" に設定されたメタデータコレクションがある場合、そのメタデータコレクションのスキーマは親コレクションのスキーマに加えられる変更の一部を継承します。この機能は保存的なものであり、メタデータコレクションが親と異なるスキーマをもつことも可能です。親スキーマから継承できる変更点は以下の点のみです。

  1. 親コレクションのスキーマに新しいフィールドを追加すると、メタデータコレクションのスキーマにも (そのフィールドが存在しないという前提の元に) 同じ名前の新しいフィールドが取得されます。この新しい列の内容は作成されませんが、明示的に設定されるまで null となります。
  2. 親コレクションのスキーマのフィールド名を変更し、メタデータコレクションのスキーマに元の名前が同じフィールドが存在する場合、このメタデータコレクションのフィールドの名前も変更されます。フィールドの内容は変更されません。

フィールドの削除などの破壊的な変更はいかなる場合でも反映されません。これらの変更は、各メタデータコレクションで手動で実行する必要があります。

このプロパティがデフォルトで "true" に設定されているのは、Excel または Google Sheets アダプターで新規作成されたメタデータコレクションのみです。このプロパティと変更継承機能は2019年7月8日にリリースされました。したがって、この日付以前に作成されたメタデータコレクションにはデフォルトで InheritsSchemaChanges プロパティは設定されていません。

エンドポイント

URL ディレクトリ

以下の表では、データサービスエンドポイントが JSON 内でリクエストまたは返すリンクの種類を一覧で示します。

https://data.app.(lucidchart/lucidpress).com/dataSets/<id>

https://data.app.(lucidchart/lucidpress).com/dataSources?dataSet=<DataSetLink>

https://data.app.(lucidchart/lucidpress).com/dataSetGrants?dataSet=<DataSetLink>

https://data.app.(lucidchart/lucidpress).com/dataSetGrants/<id>

https://data.app.(lucidchart/lucidpress).com/dataSources/<id>

https://data.app.(lucidchart/lucidpress).com/sourceGrants/<id>

https://data.app.(lucidchart/lucidpress).com/collections/<id>

https://data.app.(lucidchart/lucidpress).com/collections/<id>/metadata

https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/items/<itemId>

https://data.app.(lucidchart/lucidpress).com/collections/<id>/properties

https://data.app.(lucidchart/lucidpress).com/dataSets/<id>/properties

https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/schema/<fieldId>

https://data.app.(lucidchart/lucidpress).com/dataSets?start=<value>&end=<value>

https://data.app.(lucidchart/lucidpress).com/dataSources?start=<value>&end=<value>

https://data.app.(lucidchart/lucidpress).com/collections?start=<value>&end=<value>

https://data.app.(lucidchart/lucidpress).com/collections/<id>/items?start=<value>&end=<value>

https://data.app.(lucidchart/lucidpress).com/collections/<id>/itemsByKey?start=<value>&end=<value>

/collections/<collectionId>/schema/<fieldId>

/collections/<collectionId>/items/<itemId>

ブートストラップエンドポイント

このエンドポイントはいくつかの基本的なリンクを提供します。

URI: https://data.app.(lucidchart/lucidpress).com

例 : https://data.app.lucidchart.com

戻り値 :

{
    "dataSets": "https://data.app.lucidchart.com/dataSets",
"dataSources": "https://data.app.lucidchart.com/dataSources",
"collections": "https://data.app.lucidchart.com/collections",
"sourceGrants": "https://data.app.lucidchart.com/sourceGrants",
"dataSetGrants":"https://data.app.lucidchart.com/dataSetGrants",
"adapters": {
        <adapter name: string>: <adapter endpoint>,
        …
    }
}

データセットエンドポイント

データセットエンドポイントは、データセットの作成、削除と更新を担当します。使用可能なアクションの概要を以下に示します。ユーザーは、アクセス権限がある場合にのみ、データセットを追加/更新/削除できます。

データセット JSON オブジェクト

{
    "uri": <DataSetLink>,
    "name": <String>,
    "properties": <DataSetPropertyLink>,
    "created": <DateTime>,
    "modified": <DateTime>,
    "creatorId": <number>,
    "dataSetGrants": <DataSetGrantForDataSetLink>,
    "dataSources": <DataSetDataSourceLink>
}
すべてのデータセット数の取得

このエンドポイントは、ユーザーがアクセスできるデータセットの数を返します。戻り値はレスポンスヘッダーに Lucid-DataSets-Total: <number> として含まれます。

メソッド : HEAD

URI: https://data.app.(lucidchart/lucidpress).com/dataSets

URI の例 : https://data.app.lucidchart.com/dataSets

すべてのデータセットの取得

このエンドポイントは、ユーザーがアクセスできるすべてのデータセットを返します。結果はページ分割されます。データセットの数がページ分割の制限を超える場合は、次の結果セットまたは前の結果セット (該当する場合) を取得するためのリンクが提供されます。戻り値の範囲は、オプションの開始パラメーターと終了パラメーターにより決定できます。終了値と開始値の差がページ分割の制限より大きい場合、エンドポイントは開始から開始 + ページ分割の制限の範囲までのデータセットを返します。開始値と終了値は、データセットの作成順から派生した暗黙的な数値です。 

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSets

URI の例 : https://data.app.lucidchart.com/dataSets

クエリ文字列 :

  • ?start=<number>
  • ?end=<number>

URI の例 : https://data.app.lucidchart.com/dataSets?start=1&end=100

戻り値 :

{
    "dataSets": [<Data Set JSON Object>...],
    "total": <number>,
    "prev": Optional<DataSetPaginatedLink>,
    "next": Optional<DataSetPaginatedLink>
}

 

GET https://data.app.lucidchart.com/dataSets?start=90&end=100 からのページ分割を示すレスポンスの例 (ページ分割の制限は10) :

 

{
    "dataSets": [<Data Set JSON Object>...],
    "total": 125,
    "prev": "https://data.app.lucidchart.com/dataSets?start=80&end=90",
    "next": "https://data.app.lucidchart.com/dataSets?start=100&end=110"
}
データセットの取得

ユーザーがデータセットにアクセス可能な場合、このエンドポイントはデータセット JSON オブジェクトを返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<id>

URI の例 : https://data.app.lucidchart.com/dataSets/435

戻り値 :  データセット JSON オブジェクト

データセットの作成

このエンドポイントは、以下で指定されたペイロードを取得し、新しいデータセットと対応する新しいデータセット許可をユーザーに対して作成します。新しく作成されたデータセットのデータセット JSON オブジェクトが返されます。properties フィールドは、新しいデータセットのデータセットプロパティを作成するために使用されます。データソース内に既に存在するデータソースでデータセットを作成することはできないため、データソースの作成エンドポイントまたはデータソースの更新エンドポイントを使用してデータソースをデータセットに追加する必要があります。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/dataSets

URI の例 : https://data.app.lucidchart.com/dataSets

ペイロード : 

{
    "name": <String>,
    "properties": {
          <String>: <String>,
          …
    }
}

 

戻り値 : データセット JSON オブジェクト

 

データセット名の更新

このエンドポイントは、以下で指定されたペイロードを取得し、データセット名を更新します。更新されたデータセットのデータセット JSON オブジェクトが返されます。更新は、アクセストークンが有効で、ユーザーが対象のデータセットにアクセスできる場合にのみ行われます。このエンドポイントでデータセット内の他のフィールドを更新することはできませんので注意してください。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<id>

URI の例 : https://data.app.lucidchart.com/dataSets/435

ペイロード :


{ 
    "name": <String>
}

 

戻り値 : データセット JSON オブジェクト

 

データセットを削除

このエンドポイントは、指定されたデータセットとそれに関連するプロパティを削除します。一度削除すると、どの情報も復元できません。対象のセット内のデータソースはデータセットから削除されますが、それ以外のデータソースの削除や変更はされません。削除は、アクセストークンが有効で、ユーザーが対象のデータセットにアクセスできる場合にのみ行われます。削除に成功した場合は、成功メッセージが返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<id>

URI の例 : https://data.app.lucidchart.com/dataSets/435

データセット許可エンドポイント

これらのエンドポイントは、データセット許可の作成と削除を担当します。使用可能なエンドポイントの概要を以下に示します。各エンドポイントは、リクエストされたリソースへのアクセスを決定するために、オプションのアクセストークンを取得します。ユーザーは、適切なアクセス権限がある場合にのみ、データセット許可を作成および削除できます。

データセット許可 JSON オブジェクト

{
    "uri": <DataSetGrantLink>,
    "dataSet": <DataSetLink>,
    "permissionType": <String>,
    "identifier": <String>,
    "role": <String>,
}

 

permissionType フィールドは列挙型で示されます。有効な値は、account、document、user です。role フィールドも列挙型で示されます。有効な値は edit と view です。

 

すべてのデータセット許可の取得

このエンドポイントは、ユーザーが対象のデータセットにアクセスできる場合、特定のデータセットに対するすべてのデータセット許可を返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSetGrants

クエリ文字列 : ?dataSet=<DataSetLink>

URI の例 : https://data.app.lucidchart.com/dataSetGrants?dataSet=https://data.lucidchart.com/dataSets/435

戻り値 : データセット許可 JSON オブジェクト配列

GET https://data.app.lucidchart.com/dataSetGrantsdataSet=https://data.lucidchart.com/dataSets/435 からのレスポンスの例

[
    {
        "uri": "https://data.app.lucidchart.com/dataSetGrants/8",
"dataSet": "https://data.app.lucidchart.com/dataSets/435",
"permissionType": "account",
        "identifier": "1234",
        "role": "edit"
    },
    {
        "uri": "https://data.app.lucidchart.com/dataSetGrants/26",
"dataSet": "https://data.app.lucidchart.com/dataSets/435",
"permissionType": "user",
        "identifier": "9999",
        "role": "view"
    }
]
データセット許可の取得

このエンドポイントは、アクセストークンが有効で、ユーザーが対象のデータセットにアクセスできる場合、リクエストされたデータセット許可のデータセット許可 JSON オブジェクトを返します。URI の id は対象のデータセット許可の末尾の DataSetGrantLink であり、データセット許可 JSON オブジェクトの識別子フィールドではない点に注意してください。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSetGrants/<id>

URI の例 : https://data.app.lucidchart.com/dataSetGrants/26

戻り値 : データセット許可 JSON オブジェクト

データセット許可の作成

このエンドポイントは、データセット許可 JSON オブジェクトに似ているものの、uri フィールドが存在しない JSON オブジェクトを取得します。ユーザーが対象のデータセットにアクセスできる場合、指定したデータセットに対して新しいデータセット許可が作成されます。新しく作成されたデータセット許可のデータセット許可 JSON オブジェクトが返されます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/dataSetGrants

URI の例 : https://data.app.lucidchart.com/dataSetGrants

ペイロード : permissionType フィールドと role フィールドのいずれも文字列を取りますが、列挙型です。permissionType フィールドに有効な値は、account、document、user です。role フィールドに有効な値は edit と view です。

{
    "dataSet": <DataSetLink>,
    "permissionType": <String>,
    "identifier": <String>,
    "role": <String>
}

 

戻り値 : データセット許可 JSON オブジェクト

 

データセット許可の削除

このエンドポイントは、最後のデータセット許可に該当しない場合にのみ、指定されたデータセット許可を削除します。特定のデータセットに対して常に1つ以上のデータセット許可が必要なため、最後のデータセット許可は削除できません。削除の結果を含むレスポンスメッセージが返されます。URI の id は対象のデータセット許可の末尾の DataSetGrantLink であり、データセット許可 JSON オブジェクトの識別子フィールドではない点に注意してください。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/dataSetGrants/<id>

URI の例 : https://data.app.lucidchart.com/dataSetGrants/26

データソースエンドポイント

データソースエンドポイントは、データソースの作成、削除と更新を担当します。使用可能なアクションの概要を以下に示します。ユーザーは、アクセス権限がある場合にのみ、データソースを追加/更新/削除できます。

データソース JSON オブジェクト

{
    "uri": <DataSourceLink>,
    "name": <String>,
    "sourceGrants": <SourceGrantLink>,
    "adapterType": <String>,
    "collections": <CollectionLink>,
    "linkParameters": Optional{<String>: <String>, ...},
    "created": <DateTime>,
    "lastModified": <DateTime>,
    "deleted": Optional<DateTime>,
    "pending": <Boolean>,
    "dataSet": <DataSetLink>
}

 

adapterType フィールドは文字列で表されますが、js クライアントとデータサービスには使用可能な値の列挙型があります。有効な値には以下が含まれます。

 

  • AWS
  • BAMBOO_HR
  • CSV
  • Excel
  • GOOGLE_SHEETS
  • PROPERTY_LISTING_MLS
  • PROPERTY_LISTING_GOOGLE_SHEETS
  • PROPERTY_LISTING_ZILLOW
  • UNKNOWN (不明)

pending フラグは、クライアント経由のインポートがまだ完了していないことを示します。すべてのデータソースの取得エンドポイントは、pending フラグが true のデータソースを非表示にします。

すべてのデータソース数の取得

このエンドポイントは、ユーザーがアクセスできるデータソースの数を返します。戻り値はレスポンスヘッダーに Lucid-DataSources-Total: <number> として含まれます。

メソッド : HEAD

URI: https://data.app.(lucidchart/lucidpress).com/dataSources

URI の例 : https://data.app.lucidchart.com/dataSources

すべてのデータソースの取得

このエンドポイントは、ユーザーがアクセスできるすべてのデータソースを返します。結果はページ分割されます。データソースの数がページ分割の制限を超える場合は、次の結果セットまたは前の結果セット (該当する場合) を取得するためのリンクが提供されます。戻り値の範囲は、オプションの開始パラメーターと終了パラメーターにより決定できます。終了値と開始値の差がページ分割の制限より大きい場合、エンドポイントは開始から開始 + ページ分割の制限の範囲までのデータソースを返します。開始値と終了値は、データソースの作成順から派生した暗黙的な数値です。オプションで、エンドポイントが特定のデータセットに属するすべてのソースに絞り込む dataSet クエリパラメータを取ることができます。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSources

URI の例 : https://data.app.lucidchart.com/dataSources

クエリ文字列 :

例 : https://data.app.lucidchart.com/dataSources?start=1&end=100

戻り値 :

{
    "dataSources": [<Data Source JSON Object>...],
    "total": <number>,
    "prev": Optional<DataSourcePaginatedLink>,
    "next": Optional<DataSourcePaginatedLink>
}

 

GET https://data.app.lucidchart.com/dataSources?start=90&end=100 からのページ分割を示すレスポンスの例 (ページ分割の制限は10) :

 

{
    "dataSources": [<Data Source JSON Object>...],
    "total": 125,
    "prev": "https://data.app.lucidchart.com/dataSources?start=80&end=90",
    "next": "https://data.app.lucidchart.com/dataSources?start=100&end=110"
}
データソースの取得

ユーザーがデータソースにアクセス可能な場合、このエンドポイントはデータソース JSON オブジェクトを返します。データソースの作成者がリクエストを行うユーザーである場合、データソースとともにリンクパラメーターが返されます。 

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSources/<id>

URI の例 : https://data.app.lucidchart.com/dataSources/123

戻り値 :  データソース JSON オブジェクト

データソースの作成

このエンドポイントはデータソース JSON オブジェクトを取得し、新しいデータソースを作成します。ユーザーに対する新しいソース許可も作成され、新しく作成されたデータソースの JSON が返されます。pending フラグは、クライアント経由のインポートがまだ完了していないことを示します。すべてのデータソースを取得エンドポイントは、pending フラグが true のデータソースを非表示にします。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/dataSources

URI の例 : https://data.app.lucidchart.com/dataSources

ペイロード : 

{
    "name": <String>,
    "adapterType": Optional<String>,
    "pending": Optional<Boolean>,
    "dataSet": Optional<DataSetLink>
}

 

戻り値 : データソース JSON オブジェクト

 

データソースの更新

このエンドポイントはデータソース JSON オブジェクトを取得し、データソース名、adapterType フィールドと linkParameters フィールドを更新します。更新されたデータソースの JSON が返されます。更新は、ユーザーが対象のデータソースにアクセスできる場合にのみ行われます。linkParameters を更新できるのはデータソースの作成者のみです。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/dataSources/<id>

URI の例 : https://data.app.lucidchart.com/dataSources/55

ペイロード : 

{
    "uri": <DataSourceLink>,
    "Name": String,
    "adapterType": Optional<String>,
    "linkParameters": Optional{<String>: <String>, ...},
    "pending": Optional<Boolean>,
    "dataSet": Optional<DataSetLink>
}

 

戻り値 : データソース JSON オブジェクト

 

データソースの削除

このエンドポイントは、指定されたデータソースとそれに関連する内容 (コレクション、スキーマ、アイテム、リンクパラメーター) を削除します。一度削除すると、どの情報も復元できません。削除は、アクセストークンが有効で、ユーザーが対象のデータソースにアクセスできる場合にのみ行われます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/dataSources/<id>

URI の例 : https://data.app.lucidchart.com/dataSources/25

ソース許可エンドポイント

これらのエンドポイントは、ソース許可の作成と削除を担当します。アクションの概要を以下に示します。各エンドポイントは、リクエストされたリソースへのアクセスを決定するために、オプションのアクセストークンを取得します。ユーザーは、適切なアクセス権限がある場合にのみ、ソース許可を作成および削除できます。

ソース許可 JSON オブジェクト

{
    "uri": <SourceGrantLink>,
    "dataSource": <DataSourceLink>,
    "permissionType": <String>,
    "identifier": <String>,
    "role": <String>
}

 

permissionType フィールドは列挙型で示されます。有効な値は、account、document、user です。role フィールドも列挙型で示されます。有効な値は edit と view です。 

 

すべてのソース許可の取得

このエンドポイントは、ユーザーが対象のデータソースにアクセスできる場合、特定のデータソースに対するすべてのソース許可を返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/sourceGrants

クエリ文字列 : ?dataSource=<DataSourceLink>

URI の例 : https://data.app.lucidchart.com/sourceGrants?dataSource=https://data.lucidchart.com/dataSources/1

戻り値 : ソース許可 JSON オブジェクト配列

GET https://data.app.lucidchart.com/sourceGrants?dataSource=https://data.lucidchart.com/dataSources/1 からのレスポンスの例 

[
    {
        "uri": "https://data.app.lucidchart.com/sourceGrants/8",
"dataSource": "https://data.app.lucidchart.com/dataSources/1",
"permissionType": "account",
        "identifier": "1234",
        "role": "edit"
    },
    {
        "uri": "https://data.app.lucidchart.com/sourceGrants/1",
"dataSource": "https://data.app.lucidchart.com/dataSources/1",
"permissionType": "user",
        "identifier": "9999",
        "role": "view"
    }
]
ソース許可の取得

このエンドポイントは、アクセストークンが有効で、ユーザーが対象のデータソースにアクセスできる場合、リクエストされたソース許可のソース許可 JSON オブジェクトを返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/sourceGrants/<id>

URI の例 : https://data.app.lucidchart.com/sourceGrants/78

戻り値 : ソース許可 JSON オブジェクト

ソース許可の作成

このエンドポイントは、ソース許可 JSON オブジェクトに似た JSON オブジェクトを取得します。ユーザーが対象のデータソースにアクセスできる場合、指定したデータソースに対して新しいソース許可が作成されます。新しく作成されたソース許可の JSON が返されます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/sourceGrants

URI の例 : https://data.app.lucidchart.com/sourceGrants

ペイロード : permissionType フィールドと role フィールドのいずれも文字列を取りますが、列挙型です。permissionType フィールドに有効な値は、account、document、user です。role フィールドに有効な値は edit と view です。

{
    "dataSource": <DataSourceLink>,
    "permissionType": <String>,
    "identifier": <String>,
    "role": <String>
}

 

戻り値 : ソース許可 JSON オブジェクト

 

ソース許可の削除

このエンドポイントは、最後のソース許可に該当しない場合にのみ、指定されたソース許可を削除します。特定のデータソースに対して常に1つ以上のソース許可が必要なため、最後のソース許可は削除できません。 

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/sourceGrants/<id>

URI の例 : https://data.app.lucidchart.com/sourceGrants/536

戻り値 : "Source grant 536 deleted"

コレクションエンドポイント

コレクションエンドポイントは、コレクションの作成、更新と削除を担当します。個別のエンドポイントの概要を以下に示します。各エンドポイントは、リクエストされたコレクションへのアクセスを決定するために、オプションのアクセストークンを取得します。ユーザーは、対象のデータソースとコレクションへのアクセス権限がある場合にのみ、コレクションを追加/更新/削除できます。

コレクション JSON オブジェクト

{
    "uri": <CollectionLink>,
    "dataSource": <DataSourceLink>,
    "name": <String>,
    "lastSync": <DateTime>,
    "versionTimestamp": <DateTime>,
    "parent": Optional<CollectionLink>,
    "metadataType": Optional<String>,
    "created": <DateTime>,
    "deleted": Optional<DateTime>,
    "lastModified": <DateTime>,
    "items": <ItemLink>,
    "schema": <FieldDefinitionLink>,
    "properties": <CollectionPropertyLink>,
    "metadata": <MetadataCollectionLink>,
    "syncStarted": Optional<DateTime>
}

 

versionTimestamp フィールドは、コレクション、コレクションのスキーマ、コレクションのコンテンツ、コレクションのプロパティのいずれか、またはメタデータコレクションのいずれかが最後に変更された時刻を示します。これは、データのコピーが古いもので、更新が必要かどうかを判別するために使用できます。

 

syncStarted フィールドは、コレクションの同期ステータスを示します。null の場合、同期は行われていません。DateTime 値が存在する場合には、その値は現在実行中の同期の開始時刻を表します。

すべてのコレクション数の取得

このエンドポイントは、ユーザーがアクセスできるコレクションの数を返します。 

メソッド : HEAD

URI: https://data.app.(lucidchart/lucidpress).com/collections

URI の例 : https://data.app.lucidchart.com/collections

戻り値 : レスポンスヘッダーの field: Lucid-Collections-Total の下

すべてのコレクションの取得

このエンドポイントは、ユーザーがアクセスできるすべてのコレクションを返します。結果は既定の数にページ分割されます。コレクションの数がページ分割の制限を超える場合は、次の結果セットまたは前の結果セット (該当する場合) を取得するためのリンクが提供されます。オプションの start と end パラメーターが戻り値の範囲を決定します。終了値と開始値の差がページ分割の制限より大きい場合、エンドポイントは開始から開始 + ページ分割の制限の範囲までのコレクションを返します。開始値と終了値は、コレクションの作成順から派生した暗黙的な数値です。 

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections

URI の例 : https://data.app.lucidchart.com/collections

クエリ文字列 :

  • ?start=<number>
  • ?end=<number>

例 : https://data.app.lucidchart.com/collections?start=1&end=100

戻り値 :

{
    "collections": [<Collection JSON Object>...],
    "total": <number>,
    "prev": <CollectionPaginatedLink>,
    "next": <CollectionPaginatedLink>
}

 

GET https://data.app.lucidchart.com/collections?start=90&end=100 からのページ分割を示すレスポンスの例 (ページ分割の制限は10) :

 

{
    "collections": [<Collection JSON Object>...],
    "total": 125,
    "prev": "https://data.app.lucidchart.com/collections?start=80&end=90",
    "next": "https://data.app.lucidchart.com/collections?start=100&end=110"
}
コレクションの取得

このエンドポイントは、アクセストークンが有効で、ユーザーにアクセス権限がある場合、リクエストされたコレクション JSON オブジェクトを返します。 

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>

URI の例 : https://data.app.lucidchart.com/collections/94

戻り値 : コレクション JSON オブジェクト

戻り値の例 : 

{
    "uri": "https://data.app.lucidchart.com/collections/3",
"dataSource": "https://data.app.lucidchart.com/dataSources/1",
"name": "Some New Collection",
    "lastSync": "2018-03-28T14:48:45Z",
    "parent": null,
    "metadataType": null,
    "created": "2018-03-23T17:34:31Z",
    "deleted": null,
    "lastModified": "2018-03-28T14:48:44Z",
    "items": "https://data.app.lucidchart.com/collections/3/items",
"schema": "https://data.app.lucidchart.com/collections/3/schema",
"properties": "https://data.app.lucidchart.com/collections/3/properties",
"metadata": "https://data.app.lucidchart.com/collections/3/metadata",
"syncStarted": null
}
コレクションの作成

このエンドポイントは、新しいコレクションの作成に必要な情報を含む JSON オブジェクトを取得します。ユーザーが対象のデータソースにアクセスできる場合、新しいコレクションが作成されます。新しく作成されたコレクションのコレクション JSON オブジェクトが返されます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/collections

URI の例 : https://data.app.lucidchart.com/collections

ペイロード : 

{
    "dataSource": <DataSourceLink>,
    "name": <String>,
    "schema": [
        {
            "name": <String>,
            "fieldType": <String>,
            "default": Optional<String>,
            "order": <number>
        },
        ...
    ],
    "properties": {
        <String>: <String>,
        ...
    }
}

 

このスキーマフィールドは、各オブジェクトが単一のフィールドを示すオブジェクトの配列を取得します。fieldType フィールドは、フィールドの型を格納するために使用されます。この型はクライアント側で使用するためのもので、データサービスでのデータの解釈方法には影響しません。fieldType の有効な値は、BOOLEAN、STRING、NUMBER、ANY です。default フィールドはこのフィールドの既定値を表します。order フィールドは、1から始まるフィールドの順序を示します。

 

properties フィールドは、クライアントが使用するプロパティの文字列マッピングを格納するために使用されます。 

ペイロードの例 :

{
    "dataSource": "https://data.app.lucidchart.com/dataSources/1",
"name": "TPS Reports 2018",
    "schema": [
        {
            "name": "Name",
            "fieldType": "STRING",
            "order": 1
        },
        {
            "name": "Employee ID",
            "fieldType": "NUMBER",
            "default": "1",
            "order": 2
        }
    ],
    "properties": {
        "backgroundColor": "green",
        "fontSize": "12"
    }
}
コレクションの更新

このエンドポイントは、JSON オブジェクトを取得し、これを使用してコレクションの名前やデータソースを更新します。更新されたコレクションの JSON オブジェクトが返されます。更新は、アクセストークンが有効で、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。更新できるのは、トップレベルのコレクションのみです。メタデータコレクションの更新はできません。 

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>

URI の例 : https://data.app.lucidchart.com/collections/255

ペイロード : 

{
    "name": <String>,
    "dataSource": <DataSourceLink>
}

 

戻り値 : コレクション JSON オブジェクト

 

コレクションの削除

このエンドポイントは、コレクションとそれに属する内容 (メタデータコレクション、スキーマ、アイテム) を削除します。データソースは削除されません。この動作を復元することはできません。削除は、アクセストークンが有効で、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。 

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>

URI の例 : https://data.app.lucidchart.com/collections/67

すべてのメタデータコレクションの取得

このエンドポイントは、リクエストされたコレクションに存在するメタデータコレクションのコレクション JSON オブジェクトの一覧を返します。アクセストークンが有効で、ユーザーが対象のデータセットにアクセスできる場合にのみ値が返されます。メタデータコレクションはそれぞれ、親フィールド内の親コレクションへのリンクを含みます。 

メソッド : GET

URI: https://data.app/(lucidchart/lucidpress).com/collections/<id>/metadata

URI の例 : https://data.app.lucidchart.com/collections/88/metadata

戻り値 : コレクション JSON オブジェクト配列

メタデータコレクションの作成

このエンドポイントは、新しいメタデータコレクションの作成に使用される JSON オブジェクトを取得します。メタデータコレクションを作成するには、ユーザーに親コレクションへのアクセス権限が必要です。新しく作成されたメタデータコレクションのコレクション JSON オブジェクトが返されます。メタデータコレクションの更新はできません。 

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/metadata

URI の例 : https://data.app.lucidchart.com/collections/245/metadata

ペイロード : 

{
    "name": Optional<String>,
    "metadataType": <String>,
    "schema": [
        {
            "name": <String>,
            "fieldType": <String>,
            "default": Optional<String>,
            "order": <Number>
        },
        ...
    ],
    "properties": {
        <String>: <String>,
        ...
    }
}

 

このスキーマフィールドは、各オブジェクトが単一のフィールドを示すオブジェクトの配列を取得します。fieldType フィールドは、フィールドの型を格納するために使用されます。この型はクライアント側で使用するためのもので、データサービスでのデータの解釈方法には影響しません。fieldType の有効な値は、BOOLEAN、STRING、NUMBER、ANY です。JSON の default フィールドは、指定されていないアイテムの値の入力に使用されます。order フィールドは、1から始まるフィールドの順序を示します。

 

properties フィールドは、クライアントが使用するプロパティの文字列マッピングを格納するために使用されます。

スキーマエンドポイント

スキーマエンドポイントは、スキーマ内のフィールド定義の作成、削除と更新を担当します。スキーマはフィールド定義で構成されます。ユーザーは、対象の親コレクションへのアクセス権限がある場合にのみ、フィールド定義を追加/更新/削除できます。 

フィールド定義 JSON オブジェクト

{
    "uri": <FieldDefinitionLink>,
    "name": <String>,
    "fieldType": <String>,
    "collection": <CollectionsLink>,
    "isPrimary": <Boolean>,
    "order": Number,
    "default": Optional<String>
}

 

fieldType フィールドは、フィールドの型を格納するために使用されます。この型はクライアント側で使用するためのもので、データサービスでのデータの解釈方法には影響しません。fieldType の有効な値は、BOOLEAN、STRING、NUMBER、ANY です。

 

isPrimary フィールドは、指定されたフィールドが主キーの一部であるかどうかを示します。既定値は false です。 

order フィールドは、フィールドの既定の順序を示します。これは現在、コンテキスト上より良い順序がある場合を除き、Lucidchart/press クライアントがフィールドの表示順序を決定するために使用されています。例えば、フィールド "First Name" の order が 3 でフィールド "Last Name" の order が 1 の場合、クライアントは名前列の順序を既定で "Last Name" が先、"First Name" が後に表示します。また、クライアントが order フィールドを isPrimary と組み合わせ、フィールドでソートされた主キーで構成されるクライアントのみの複合キーを作成することもあります。データサービス自体がこのプロパティの使用や検証を行うことはありません。 

default フィールドはこのフィールドの既定値を表します。

すべてのフィールド定義の取得

このエンドポイントは、ユーザーが対象のコレクションにアクセスできる場合、特定のコレクションのすべてのフィールド定義を返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/schema

戻り値 : フィールド定義 JSON オブジェクト配列

戻り値の例 :

[
    {
        "uri": "https://data.app.lucidchart.com/collections/1/schema/1",
"name": "colA",
        "fieldType": "STRING",
        "collection": "https://data.app.lucidchart.com/collections/1",
"isPrimary": false,
        "order": 2,
        "default": "foo"
    },
    {
        "uri": "https://data.app.lucidchart.com/collections/1/schema/2",
"name": "colB",
        "fieldType": "NUMBER",
        "collection": "https://data.app.lucidchart.com/collections/1",
"isPrimary": true,
        "order": 1,
        "default": null
    }
]
フィールド定義の取得

このエンドポイントは、ユーザーが対象のコレクションにアクセスできる場合、特定のコレクションの特定のフィールド定義を返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/schema/<fieldId>

URI の例 : https://data.app.lucidchart.com/collections/34/schema/27

戻り値 : フィールド定義 JSON オブジェクト

戻り値の例 : 

{
    "uri": "https://data.app.lucidchart.com/collections/34/schema/27",
"name": "field one",
    "fieldType": "STRING",
    "collection": "https://data.app.lucidchart.com/collections/34",
"isPrimary": true,
    "order": 2,
    "default": "test"
}
フィールド定義の更新

このエンドポイントでは、複数のフィールド定義を一度に更新できます。この操作は、すべてのフィールド定義の取得エンドポイントからのレスポンスの値を変更し、PATCH リクエストを送信すると、簡単に行なえます。値を変更すると、コレクションのスキーマ内の既存のフィールド定義が更新されます。スキーマ内の name フィールドが一意である場合、uri フィールドなしで送信されたフィールドはすべてスキーマに追加されます。このエンドポイントでフィールドを削除することはできません。 

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/schema

URI の例 : https://data.app.lucidchart.com/collections/62/schema

ペイロード : フィールド定義 JSON オブジェクト配列

戻り値 : フィールド定義 JSON オブジェクト配列。新規または更新されたフィールド定義のみを返します。

フィールド定義の更新

このエンドポイントは、指定されたフィールド定義の更新に使用されるフィールド定義 JSON オブジェクトを取得します。この操作は、フィールド定義の取得エンドポイントからのレスポンスの値を変更し、PATCH リクエストを送信すると、簡単に行なえます。このエンドポイントは、更新されたフィールド定義のフィールド定義 JSON オブジェクトを返します。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/schema/<fieldId>

URI の例 : https://data.app.lucidchart.com/collections/22/schema/4

ペイロード : フィールド定義 JSON オブジェクト

戻り値 : フィールド定義 JSON オブジェクト

フィールド定義の削除

このエンドポイントは、クエリパラメーターで指定されたフィールド定義のみを削除します。対象のクエリパラメーターのフィールドは指定されたコレクションに属している必要があります。この削除の結果を元に戻すことはできません。削除は、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。

*スキーマ全体を削除すると、各データアイテムの値もすべて削除されますので注意してください。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/schema

クエリパラメーター : ?fields=<FieldDefinitionLink or RelativeFieldDefinitionLink>,...

URI の例 : https://data.app.lucidchart.com/collections/41/schema?fields=https://data.app.lucidchart.com/collections/41/schema/21,/collections/41/schema/22

フィールド定義の削除

このエンドポイントは、コレクションのスキーマからフィールド定義を削除します。このアクションの結果を元に戻すことはできません。削除は、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。このアクションにより、削除されたフィールドに関連付けられているデータアイテムの値もすべて削除されます。 

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/schema/<fieldId>

URI の例 : https://data.app.lucidchart.com/collections/144/schema/12

データアイテムエンドポイント

データアイテムエンドポイントは、コレクション内のデータアイテムの作成、削除と更新を担当します。アクションの概要を以下に示します。ユーザーは、対象の親コレクションへのアクセス権限がある場合にのみ、データアイテムを追加/更新/削除できます。

データアイテム JSON オブジェクト

{
    "uri": <ItemLink>,
    "collection": <CollectionLink>,
    "fields": {
        <field name>: <String>,
        ...
    }
}

 

データアイテムはそれぞれ、URI、コレクションとフィールドのリストから構成されます。フィールドは、スキーマフィールド名からデータアイテム値へのマッピングで構成されます。フィールド名はそれぞれ、コレクションのスキーマ内の一致するフィールドに対応します。データアイテムに各スキーマフィールドに特定の値が指定されていない場合、スキーマフィールドの既定値または null が適用されます。 

 

キーによるデータアイテム検索 JSON オブジェクト
{
    "keySchemaFields": Optional<[Strings]>,
"targetValues": [{
    "fieldValues": [String],
}, … ]
}

 

キーによるデータアイテム検索 JSON オブジェクトは、キーによるデータアイテムの検索に使用されます (キーによるデータアイテムの取得およびキーによるデータアイテムの削除を参照)。

 

オプションの keySchemaFields パラメーターは、コレクション内のアイテムの検索に使用するフィールドを定義します。これが指定されていない場合、データサービスはスキーマエンドポイントの主キーを使用します。

targetValues パラメーターには、検索するコレクション内のアイテムを定義するオブジェクトの配列を指定します。targetValues のオブジェクトにはそれぞれ、このエンドポイントがフィールドに関して検出する必要がある実際の値を指定する単一のパラメーター fieldValues が含まれています。fieldValues 内の文字列の順序は、keySchemaFields の順序、またはkeySchemaFields が定義されていない場合には実際のスキーマの実際の主キーの順序と一致する必要があります。

キーによるデータアイテムパッチ JSON オブジェクト

{
    "keySchemaFields": Optional<[String]>
    "patches": [{
        "fieldValues": [String],
        "patch": {
            <Field name>: <String> or null
}
    }, ...]
}

 

PATCH リクエストのキーによりデータアイテムを検索し、パッチを適用するために使用します (キーによるデータアイテムの更新を参照)。

 

オプションの keySchemaFields パラメーターは、POST リクエストの keySchemaFields 同様、チェックすべきスキーマフィールドとリクエストの残りの順序を記述します。

patches パラメーターは、変更するコレクションのアイテムを定義するオブジェクトの配列です。patches 内の各オブジェクトには fieldValues パラメーターが含まれ、これはキーによるデータアイテム検索 JSON オブジェクトセクションでの説明の通りに機能します。 

patch オブジェクトは、一致するアイテムに適用される変更を表します。<Field name> はそれぞれ、変更されるフィールドを指定し、<String> または null 値はフィールドに設定する新しい値を定義します。値が null の場合、そのフィールドは一致するデータアイテムから削除されます。

すべてのデータアイテム数の取得

このエンドポイントは、指定されたコレクション内のアイテムの数を返します。

メソッド : HEAD

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/items

URI の例 : https://data.app.lucidchart.com/collections/31/items

戻り値 : レスポンスヘッダーの field: Lucid-Items-Total の下の数字

すべてのデータアイテムの取得

このエンドポイントは、指定されたコレクション内のすべてのデータアイテムを返します。結果は既定の数にページ分割されます。データアイテムの数がページ分割の制限を超える場合は、次の結果セットまたは前の結果セット (該当する場合) を取得するためのリンクが提供されます。オプションの start と end パラメーターが戻り値の範囲を決定します。終了値と開始値の差がページ分割の制限より大きい場合、エンドポイントは開始から開始 + ページ分割の制限の範囲までのデータアイテムを返します。開始値と終了値は、データアイテムの作成順から派生した暗黙的な数値です。 アイテムの合計数はヘッダーの "Lucid-Items-Total" にも表示されます。

このエンドポイントは、オプションのフィルター文字列にも対応しています。この文字列を使用して、items フィールドの値に基づいて返されるデータアイテムをフィルタリングできます。フィルターが含まれる場合、startend パラメーターはフィルターに一致するアイテムのみを参照します。これは、レスポンス内の total 値についても同様です。詳細は以下のデータアイテムフィルターを参照してください。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/items

URI の例 : https://data.app.lucidchart.com/collections/44/items

クエリ文字列 :

  • ?start=<number>
  • ?end=<number>
  • ?filter=<string>

例 : https://data.app.lucidchart.com/collections/44/items?start=1&end=100&filter=age%20%3E%2016.

フィルタ文字列は URL エンコードされていますので注意してください。エンコードされていない状態では "filter=age > 16" となります。

戻り値 :

{
    "items": [<Data Item JSON Object>...],
    "total": <number>,
    "prev": <ItemPaginatedLink>,
    "next": <ItemPaginatedLink>
}

 

GET https://data.lucidchart.com/collections/44/items?start=90&end=100 からのページ分割を示すレスポンスの例 (ページ分割の制限は10) :

 

{
    "items": [<Data Item JSON Object>...],
    "total": 125,
    "prev": "https://data.app.lucidchart.com/collections/44/items?start=80&end=90",
    "next": "https://data.app.lucidchart.com/collections/44/items?start=100&end=110"
}

 

コレクションが更新されている場合、このリクエストは 423 LOCKED エラーを返します。

 

データアイテムフィルター

データアイテムフィルターは、すべてのデータアイテムの取得エンドポイントでオプションで使用できるクエリ文字列で、データサービスから取得するアイテムの制限を目的としたものです。このセクションでは、構文と制限事項について説明します。

アイテムフィルター式の中心となる要素は、比較です。比較はそれ自体、最もシンプルかつ有効なフィルターとなります。すべての比較は厳密に <fieldname> <operator> <constant> の形式を取ります。この順序が重要で、フィールド名は左側に、定数は右側でなければなりません。比較の簡単な例 : フィルター name = "James" を使用すると、フィールド name に値 "James" があるアイテムにのみ結果が絞り込まれます。数値比較を行う場合は、age > 21 などのフィルターを使用することができます。文字列定数は引用符で囲まれていますが、数値定数は引用符で囲まれません。

フィールド

フィルター対象のフィールド名にスペースなどの特殊文字が含まれる場合には、"'` の3つの簡単な引用符のいずれかでフィールド名を囲むことができます。したがって、文字列 "full name" = "John Smith" はフィールド full name について有効な比較となります。フィールド名に引用符が含まれている場合は、フィールド名を他の引用符文字のいずれかで囲む (推奨) か、フィールド名内の引用符を二重にすることでエスケープできます。例えば、フィールド名 "I can't even" は "I can't even" または 'I can''t even' として示すことができます。

演算子

比較に使用できる演算子は7つあります。

オペレーター

有効な定数タイプ

ノート

=

文字列、数値

等号は文字列と整数でうまく機能します。浮動小数点数について等号を使用するのは困難です。これは非常に複雑な問題なため、問題が発生した場合には、他の特殊なリソースを検索することをお勧めします。

!=

文字列、数値

比較と型強制に関する注意事項セクションでの説明の通り、= と != は、定数と比較可能なフィールド値の逆を示します。

>

文字列、数値

 

次の値より多いか等しい

文字列、数値

 

<

文字列、数値

 

次の値より少ないか等しい

文字列、数値

 

in

文字列、数値または文字列の配列

定数が文字列または数値の場合は、単一の要素を持つ文字列または数値の配列として扱われます。

文字列の比較ではいずれも大文字と小文字が区別されません。

比較と型強制に関する注意事項

すべての演算子につき、結果が true になるには、フィールドの値が定数と比較可能であるとみなされる必要があります。例えば、定数が数値である場合、比較が実行される前にフィールドが数値に強制変換されます。フィールドを数値に強制変換できない場合、比較の結果は false となります。例えば、値が "0.0" のフィールドは数値定数 0 と等しいものの、文字列定数 "0" とは等しくありません。また、"a" は数値に強制変換できないため、値が "a" のフィールドは "a" = 0"a" != 0 の両方につき false を返します。同様に、定数が文字列の配列である場合、関連する演算子が IN である場合にのみ比較の結果が true となります。これ以外の演算子と配列定数との組み合わせはすべて、自動的に false となります。

定数

定数には、引用符で囲まれた文字列、数値、または文字列の配列のいずれかを指定できます。

定数が単純な引用符 (" 、' や `) で囲まれている場合には文字列となります。引用符で囲まれた文字列内に引用符を含めるには、フィールド名と同様に、他の引用符を使用するか、文字列内の任意の場所に引用符を2回繰り返してエスケープします。

定数が引用符や括弧で囲まれていない場合は数値となり、有効な浮動小数点数として Java で解析することができます。

定数がコンマ区切りの文字列のリストを括弧で囲んだ形式の場合には文字列の配列となります。文字列の配列は IN 演算子を使用する場合にのみ評価されます。配列に他の演算子が使用されている場合には、自動で false と評価されます。文字列の配列を使用した比較の例 "name IN ("Peter", "Paul", "Mary")" では、名前が "Peter"、"Paul"、"Mary" のいずれかである場合にのみ true として評価されます。

複合フィルター

オペレーター

優先順位

結果

NOT

この演算子の直後にフィルターの結果の逆を返します

AND

複合フィルターは、この演算子の前後のフィルターが両方とも true である場合にのみ true となります

論理和

この演算子の前または後のフィルターが true である場合は true となります

 

例えば、名前が "Thomas" または "Susan" でないすべてのアイテムに一致させる場合には、複合フィルター NOT name IN ("Thomas", "Susan") を使用することができます。.また、年齢が8歳未満または10歳超の人を抽出するには、複合フィルター age < 8 OR age > 10 を使用できます。さらに、名が "Chris" で、かつ姓が "Smith" または "Wesson" でない人のみを抽出するには、複合フィルター first_name = "Chris" AND NOT last_name IN ("Smith", "Wesson") を使用できます。

以下では、さらに複雑な複合フィルターの例とその優先順位を紹介しています。

age > 21 AND NOT last_name in ("Smith", "Wesson") OR as_adult = "true".

このフィルターは、フィールド as_adult が値 "true" に設定されているコレクションのすべてのアイテムを返します。さらに、age (年齢) が21歳超で、last_name (姓) が "Smith" でも "Wesson" でもないすべてのアイテムも返します。これらの条件の両方を満たすアイテムがある場合は結果に含まれますが、含まれるのは一度だけとなります。この内容は、以下のフィルターと等しくなりますが、

((age > 21 AND (NOT last_name in ("Smith", "Wesson"))) OR as_adult = "true")

以下のフィルターとは異なります。

age > 21 AND (NOT last_name in ("Smith", "Wesson") OR as_adult = "true")

最後のフィルターは、age が21歳超で、かつ、as_adult が "true" に設定されている、または last_name が "Smith" でも "Wesson" でもないアイテムのみを返します。

フィルター構文全文

フィルター文字列の完全な構文は、以下の定義によって与えられます。

filter = comparison | composite filter

comparison = fieldname operator constant
fieldname = identifier | quotedstring
identifier = <a sequence of non-whitespace chars>
quotedstring = ("|'|`)<Any string with escaped quotes>("|'|`) (both of the outer quotes must be the same symbol)

operator = '=' | '!=' | '>' | '>=' | '<' | '<=' | 'IN'
constant = stringconstant | numberconstant | stringarray
stringconstant = quotedstring
numberconstant = <any non-quoted string (without whitespace) that Java parses as a valid double>
stringarray = '(' stringconstant [, stringconstant... ] ')'

composite filter = notfilter | andfilter | orfilter
notfilter = 'NOT' filter
andfilter = filter 'AND' filter
orfilter = filter 'OR' filter
データアイテムの取得

このエンドポイントは、指定されたデータアイテムのデータアイテム JSON オブジェクトを返します。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/items/<itemId>

URI の例 : https://data.app.lucidchart.com/collections/51/items/12

戻り値 : データアイテム JSON オブジェクト

GET https://data.lucidchart.com/collections/51/items/11 からのレスポンスの例

{
    "uri": "https://data.app.lucidchart.com/collections/51/items/12",
"collection": "https://data.app.lucidchart.com/collections/51",
"fields": {
        "ColA": "123",
        "ColB": "456",
        "ColC": null
    }
}
キーによるデータアイテムの取得

このエンドポイントは、キーによるデータアイテム検索 JSON オブジェクトで指定された値と一致するフィールド値をもつ、指定されたコレクション内のすべてのデータアイテムを返します。必要に応じて、以下のクエリパラメーターを使用して、このエンドポイントの結果をページ分割できます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/itemsByKey

URI の例 : https://data.app.lucidchart.com/collections/123/itemsByKey

クエリ文字列 :

  • ?start=<number>
  • ?end=<number>

例 : https://data.app.lucidchart.com/collections/123/itemsByKey?start=1&end=100

ペイロード : キーによるデータアイテム検索 JSON オブジェクト

戻り値 :

{
    "items": [<Data Item JSON Object>,...],
    "total": <number>,
    "prev": Optional<ItemsByKeyPaginatedLink>,
    "next": Optional<ItemsByKeyPaginatedLink>
}

 

ペイロードの例 :

 

{
    "keySchemaFields": ["first name", "last name"
    "targetValues": [
        {
        "fieldValues": ["Joey", "Ontario"]
        },
        {
        "fieldValues": ["Sheela", "Indigo"]
        }
    ]
}

 

レスポンスの例 :

 

{
    "items": [<Data Item JSON Object>,...],
    "total": 450,
    "prev": "https://data.app.lucidchart.com/collections/123/itemsByKey?start=1&end=100",
    "next": "https://data.app.lucidchart.com/collections/123/itemsByKey?start=201&end=300"
}

 

さらに複雑なデータアイテム検索クエリを行う場合は、すべてのデータアイテムの取得エンドポイントで filter パラメーターを使用することを検討してください。

 

新しいアイテムの作成

このエンドポイントは、作成するスキーマフィールドとデータアイテムの値を表す JSON オブジェクトのリストを取得します。ユーザーが対象のコレクションにアクセスできる場合、指定された値を使用して新しいデータアイテムが作成されます。主キーの制約は適用されません。スキーマ定義の一部ではないフィールド名はデフォルトで無視されます。スキーマは、データアイテムの作成前に作成する必要があります。新しく作成されたデータアイテムのデータアイテム JSON オブジェクトが返されます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/items

URI の例 : https://data.app.lucidchart.com/collections/61/items

ペイロード :

[
    {
        <Field name>: <String>,
        ...
    },
    ...
]

 

戻り値 : データアイテム JSON オブジェクト配列

 

スキーマ内で "ColA" と "ColB" のみが定義されているコレクションへのペイロードの例 :

[
    {
        "ColA": "a value",
        "ColB": "b value"
    },
    {
        "ColA": "aa value",
        "ColB": "bb value",
        "ColC": "cc value"
    }
]

 

"ColC" がスキーマで定義されていないため、2番目のオブジェクトの ColC 値は作成されません。

 

レスポンスの例 :

[
    {
        "uri": "https://data.app.lucidchart.com/collections/61/items/3",
"collection": "https://data.app.lucidchart.com/collections/61",
"fields": {
            "ColA": "a value",
            "ColB": "b value"
        }
    },
    {
        "uri": "https://data.app.lucidchart.com/collections/61/items/4",
"collection": "https://data.app.lucidchart.com/collections/61",
"fields": {
            "ColA": "aa value",
            "ColB": "bb value"
        }
    }
]
データセットの更新

このエンドポイントでは、複数のデータアイテムを一度に更新できます。この操作は、すべてのデータアイテムの取得エンドポイントからのレスポンスの値を変更し、PATCH リクエストを送信すると、簡単に行なえます。値を変更すると、既存のデータアイテムの値が更新されます。データアイテムを別のコレクションに移動できないため、collection フィールドは無視されます。new の値が null の場合には、その値が削除されたことを意味します。指定されたフィールド名がコレクションスキーマに存在しない場合、その値は無視されます。エンドポイントは、更新されたデータアイテム JSON オブジェクトのリストを返します。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/items

URI の例 : https://data.app.lucidchart.com/collections/22/items

ペイロード : データアイテム JSON オブジェクト配列

戻り値 : データアイテム JSON オブジェクト配列。新規または更新されたデータアイテムのみを返します。

スキーマ内の2つのフィールドが "ColA" と "ColB" であるコレクションへのペイロードの例 :

[
    {
        "uri": "https://data.app.lucidchart.com/collections/22/items/3",
"collection": "https://data.app.lucidchart.com/collections/22",
"fields": {
            "ColA": "new a value",
            "ColB": null
        }
    },
    {
        "uri": "https://data.app.lucidchart.com/collections/22/items/4",
"collection": "https://data.app.lucidchart.com/collections/22",
"fields": {
            "ColA": "new aa value",
            "ColB": "new bb value",
            "ColC": "should not show up"
        }
    }
]

 

上記のリクエストからの戻り値の例 :

 

[
    {
        "uri": "https://data.app.lucidchart.com/collections/22/items/3",
"collection": "https://data.app.lucidchart.com/collections/22",
"fields": {
            "ColA": "new a value"
        }
    },
    {
        "uri": "https://data.app.lucidchart.com/collections/22/items/4",
"collection": "https://data.app.lucidchart.com/collections/22",
"fields": {
            "ColA": "new aa value",
            "ColB": "new bb value"
        }
    }
]
データアイテムの更新

このエンドポイントは、指定されたアイテムの値の更新に使用されるデータアイテム JSON オブジェクトを取得します。この操作は、データアイテムの削除エンドポイントからのレスポンスの値を変更し、PATCH リクエストを送信すると、簡単に行なえます。データアイテムを別のコレクションに移動できないため、collection フィールドは無視されます。new の値が null の場合には、その値が削除されたことを意味します。指定されたフィールド名がコレクションスキーマに存在しない場合、その値は無視されます。エンドポイントは、更新されたデータアイテム JSON オブジェクトを返します。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/items/<itemId>

URI の例 : https://data.app.lucidchart.com/collections/51/items/41

ペイロード : データアイテム JSON オブジェクト

戻り値 : データアイテム JSON オブジェクト

スキーマ内の2つのフィールドが "ColA" と "ColB" であるコレクションへのペイロードの例 :

{
    "uri": "https://data.app.lucidchart.com/collections/51/items/41",
"collection": "https://data.app.lucidchart.com/collections/51",
"fields": {
        "ColA": "new a value",
        "ColB": null,
        "ColC": "new c value"
    }
}

 

上記のリクエストからの戻り値の例 :

 

{
    "uri": "https://data.app.lucidchart.com/collections/51/items/41",
"collection": "https://data.app.lucidchart.com/collections/51",
"fields": {
        "ColA": "new a value"
    }
}
キーによるデータアイテムの更新

このエンドポイントでは、指定した値に一致するフィールドを持つデータアイテムを検索し、パッチを使用してそれらのアイテムを更新できます。パッチ内のフィールドの値が null の場合、その値はアイテムから削除されます。指定されたフィールド名がコレクションスキーマに存在しない場合、その値は無視されます。データアイテムを別のコレクションに移動することはできないため、collection フィールド更新の試行は無視されます。リクエストが完了すると、更新されたアイテムの数を示す文字列が返されます。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/itemsByKey

URI の例 : https://data.app.lucidchart.com/collections/22/itemsByKey

ペイロード : キーによるデータアイテムパッチ JSON オブジェクト

ペイロードの例 :

{
    "keySchemaFields": ["First Name", "Last Name"],
    "patches": [{
        "fieldValues": ["Alex", "Rowland"],
        "patch": {
            "First Name": "Jordan",
            "Last Name": "Haron"
}
    }, ...]
}

 

戻り値 : 更新されたアイテムの数を示す文字列

 

レスポンスの例 : "Updated 1 item(s)"

データアイテムの削除

このエンドポイントは、クエリパラメーターで指定されたデータアイテムのみを削除します。対象のクエリパラメーターのデータアイテムは指定されたコレクションに属している必要があります。この削除を復元することはできません。削除は、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。削除の結果を含むレスポンスメッセージが返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/items

クエリパラメーター : ?items=<ItemLink or RelativeItemLink>,...

URI の例 : https://data.app.lucidchart.com/collections/2/items?items=/collections/2/items/5,/collections/5/items/6

戻り値 : OK: 200 (成功した場合はメッセージあり)

データアイテムの削除

このエンドポイントは、コレクションから指定されたデータアイテムを削除します。この削除を復元することはできません。削除は、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。削除の結果を含むレスポンスメッセージが返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<collectionId>/items/<itemId>

URI の例 : https://data.app.lucidchart.com/collections/55/items/11

戻り値 : OK: 200 (成功した場合はメッセージあり)

キーによるデータアイテムの削除

このエンドポイントは、キー値がペイロードで指定されたアイテムに一致するすべてのアイテムを検索し、削除します。削除したアイテムの復元はできません。リクエストが完了すると、削除されたアイテムの数を示す文字列が返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/itemsByKey

URI の例 : https://data.app.lucidchart.com/collections/55/itemsByKey

ペイロード : キーによるデータアイテム検索 JSON オブジェクト

ペイロードの例 :

{
    "keySchemaFields": ["First Name", "Last Name"],
"targetValues": [{
    "fieldValues": ["Jordan", "Haron"]
}, {
    "fieldValues": ["Alex", "Rowland"]
}]
}

 

戻り値 : OK: 200 (成功した場合はメッセージあり)

 

レスポンスの例 : "Deleted 1 item(s)"

コレクションプロパティエンドポイント

コレクションプロパティエンドポイントは、コレクションに関連するプロパティの作成、削除と更新を担当します。使用可能なエンドポイントの概要を以下に示します。ユーザーは、対象の親コレクションへのアクセス権限がある場合にのみ、プロパティを追加/更新/削除できます。

コレクションプロパティ JSON オブジェクト

{
    <Property name>: <String>,
    ...
}
プロパティの取得

このエンドポイントは、ユーザーが対象のコレクションにアクセスできる場合、指定されたコレクションのすべてのプロパティを返します。プロパティはコレクションプロパティ JSON オブジェクトとして返されます。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/properties

URI の例 : https://data.app.lucidchart.com/collections/77/properties

戻り値 : コレクションプロパティ JSON オブジェクト

戻り値の例 :

{
    "backgroundColor": "blue",
    "font": "Times New Roman"
}
プロパティの更新

ユーザーはこのエンドポイントを使用してコレクションのプロパティを更新できます。このエンドポイントは、コレクションプロパティ JSON オブジェクトを取得し、指定された値を使用して既存のプロパティを更新するか、新しいプロパティを作成します。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/properties

URI の例 : https://data.app.lucidchart.com/collections/123/properties

ペイロード : コレクションプロパティ JSON オブジェクト

戻り値 : 影響を受けるプロパティのみを含むコレクションプロパティ JSON オブジェクト

例 :

以下のプロパティをもつコレクションがあり、

{
    "property1": "a",
    "property2": "b"
}

 

以下のパッチが適用される場合、

 

{
    "property2": "bb",
    "property3": "c"
}

 

以下の戻り値が返され、

 

{
    "property2": "bb",
    "property3": "c"
}

 

コレクションのプロパティは以下のようになります。

 

{
    "property1": "a",
    "property2": "bb",
    "property3": "c"
}
プロパティの削除

このエンドポイントは、クエリパラメーターで指定されたプロパティのみを削除します。削除されたプロパティを復元することはできません。削除は、ユーザーが対象のコレクションにアクセスできる場合にのみ行われます。削除の結果を含むレスポンスメッセージが返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/collections/<id>/properties

クエリパラメーター : ?properties=<property name>,...

URI の例 : https://data.app.lucidchart.com/collections/55/properties?properties=property1,property2

戻り値 : OK: 200 (成功した場合はメッセージあり)

データセットプロパティエンドポイント

データセットプロパティエンドポイントは、データセットに関連するプロパティの作成、削除と更新を担当します。使用可能なエンドポイントの概要を以下に示します。ユーザーは、対象の親データセットへのアクセス権限がある場合にのみ、プロパティを追加/更新/削除できます。

データセットプロパティ JSON オブジェクト

{
    <Property name String>: <String>,
    ...
}
データセットプロパティの取得

このエンドポイントは、ユーザーが対象のデータセットにアクセスできる場合、指定されたデータセットのすべてのプロパティを返します。プロパティはデータセットプロパティ JSON オブジェクトとして返されます。

メソッド : GET

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<dataset id>/properties

URI の例 : https://data.app.lucidchart.com/dataSets/435/properties

戻り値 : データセットプロパティ JSON オブジェクト

戻り値の例 :

{
    "backgroundColor": "blue",
    "font": "Times New Roman"
}
データセットプロパティの更新

ユーザーはこのエンドポイントを使用してデータセットのプロパティを更新できます。このエンドポイントは、データセットプロパティ JSON オブジェクトを取得し、指定された値を使用して既存のプロパティを更新するか、新しいプロパティを追加します。

メソッド : PATCH

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<data set id>/properties

URI の例 : https://data.app.lucidchart.com/dataSets/435/properties

ペイロード : データセットプロパティ JSON オブジェクト

戻り値 : 影響を受けるプロパティのみを含むデータセットプロパティ JSON オブジェクト

例 :

以下のプロパティをもつコレクションがあり、

{
    "property1": "a",
    "property2": "b"
}

 

以下のパッチが適用される場合、

 

{
    "property2": "bb",
    "property3": "c"
}

 

以下の戻り値が返され、

 

{
    "property2": "bb",
    "property3": "c"
}

 

コレクションのプロパティは以下のようになります。

 

{
    "property1": "a",
    "property2": "bb",
    "property3": "c"
}
データセットプロパティの削除

このエンドポイントは、クエリパラメーターで指定されたプロパティのみを削除します。削除されたプロパティを復元することはできません。削除は、ユーザーが対象のデータセットにアクセスできる場合にのみ行われます。削除の結果を含むレスポンスメッセージ文字列が返されます。

メソッド : DELETE

URI: https://data.app.(lucidchart/lucidpress).com/dataSets/<data set id>/properties

クエリパラメーター : ?properties=<property name>,...

URI の例 : https://data.app.lucidchart.com/dataSet/435/properties?properties=property1,property2

アダプター

CSV アダプター

CSV ファイルからの新しいデータソースの作成

このエンドポイントには、ファイルが添付されたマルチパートフォームデータが必要となります。このエンドポイントにファイルなしでリクエストを送信すると、400: Bad Request レスポンスが返されます。エンドポイントが添付ファイルを CSV ファイルとして正常に解析できた場合、このエンドポイントは 1 つのコレクションをもつデータソース (添付ファイルと同名) を作成し、新規作成されたデータソースについてデータソース JSON オブジェクトを返します。CSV を解析できない場合は、400: Bad Request レスポンスが返されます。

新規作成されたデータソース内の 1 つのコレクションには、CSV ファイルのデータが含まれます。各行がアイテムとなり、各列に元のファイルと同じ順序で A、B、C … AA、AB、AC ... とラベルが付与されます。

作成された各アイテムの id と、そのアイテムの作成元の行の元の行番号との間のマッピングを表す単一のメタデータコレクションが作成されます。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/adapter/csv

クエリ文字列 :

permissionType (任意): データソースの許可の権限のタイプ ("account"、"user"、"document" のいずれか)、下位互換性のため既定では "user"

URI の例 : https://data.lucidchart.com/adapter/csv

ペイロード : CSV ファイルが添付されたマルチパートフォームデータ

戻り値 : データソース JSON オブジェクト

既存のデータソースまたはコレクションを新しい CSV ファイルで上書き

このエンドポイントには、CSV ファイルが添付されたマルチパートフォームデータが必要となります。このエンドポイントにファイルなしでリクエストを送信すると、400: Bad Request レスポンスが返されます。エンドポイントが添付ファイルを CSV ファイルとして正常に解析でき、ターゲットとなるデータソースまたはコレクションが置換可能である (詳細は以下参照) 場合、このエンドポイントは変更されたデータソース JSON オブジェクトを返します。コレクション内で実際に変更されるのはアイテムのみであるため、変更後のオブジェクトは元のデータソース JSON オブジェクトとよく似ていますが、関連するアイテムは変更されています。添付ファイルを CSV ファイルとして解析できない場合は、400: Bad Request レスポンスが返されます。

dataSource クエリ文字列は必須です。これが含まれていない場合、400: Bad Request レスポンスが返されます。ユーザーに指定されたデータソースへのアクセス権限がない場合には、403: Forbidden レスポンスが返されます。指定したデータソースにコレクションが 1 つしか含まれていない場合には、データソースのリンクを指定すれば、エンドポイントがこのコレクションの内容を新しいデータで上書きします。コレクション参照は変更されませんが、新しいアイテムがあります。データソースに複数のコレクションがあり、リクエストにコレクションクエリパラメーターが含まれていない場合、エンドポイントは 400: Bad Request レスポンスを返します。

データソース内の特定のコレクションは、データソースとコレクションのクエリパラメーターの両方を含めて置き換えることができます。この場合、対象の単一のコレクション内のアイテムは、CSV の値で上書きされます。ターゲットコレクションの ID に変更はなく、元のコレクションは同じままでアイテムのみが変更されます。指定したコレクションは、指定のデータソースに属している必要があります。指定したデータソースに属していない場合、ユーザーのターゲットコレクションへのアクセス権限の有無に応じ、403: Forbidden または 400: Bad Request が結果として返されます。

メソッド : PUT

URI: https://data.app.(lucidchart/lucidpress).com/adapter/csv

クエリ文字列 :

URI の例 : https://data.app.lucidchart.com/adapter/csv?dataSource=https://data.app.lucidchart.com/dataSources/12&collection=https://data.lucidchart.com/collections/55

ペイロード : CSV ファイルが添付されたマルチパートフォームデータ

戻り値 : データソース JSON オブジェクト

Excel アダプター (*.xlsx ファイルのみ)

*.xlsx ファイルからの新しいデータソースの作成

このエンドポイントには、CSV ファイルが添付されたマルチパートフォームデータが必要となります。このエンドポイントにファイルなしでリクエストを送信すると、400: Bad Request レスポンスが返されます。エンドポイントが添付ファイルを Excel (*.xlsx) ファイルとして正常に解析できた場合、このエンドポイントは、添付ファイルと同名で、添付の Excel ファイル内の各タブにつき新しいコレクションを含むデータソースを作成します。新しく作成されたデータソースを示すデータソース JSON オブジェクトが返されます。ファイルを *.xlsx ファイルとして解析できない場合には、400: Bad Request レスポンスが返されます。

新規作成されたデータソース内の各コレクションには、Excel ファイルの対応するタブのデータと名前が含まれます。タブの各行がアイテムとなり、各列に元のファイルと同じ順序で A、B、C … AA、AB、AC ... とラベルが付与されます。コレクションはそれぞれ、各セルの追加情報を表す次の6つのメタデータコレクションももちます (1. 行の順序、2. 形式 (数値/文字列の表示方法)、3. 塗り潰しの色、4. 式 (結果の値でなく式自体)、5. テキストの色、6. コメント) 。

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/adapter/excel

クエリ文字列 :

permissionType (任意): データソースの許可の権限のタイプ ("account"、"user"、"document" のいずれか)、下位互換性のため既定では "user"

URI の例 : https://data.app.lucidchart.com/adapter/excel

ペイロード : Excel (*.xlsx) ファイルが添付されたマルチパートフォームデータ

戻り値 : データソース JSON オブジェクト

既存のデータソースまたはコレクションを新しい *.xlsx ファイルで上書き

このエンドポイントには、ファイルが添付されたマルチパートフォームデータが必要となります。このエンドポイントにファイルなしでリクエストを送信すると、400: Bad Request レスポンスが返されます。エンドポイントが添付ファイルを Excel (*.xlsx) ファイルとして正常に解析できた場合、このエンドポイントは、添付ファイルの内容に一致するようデータソースを変更します。成功すると、変更されたデータソースを表すデータソース JSON オブジェクトが返されます。変更されたのは関連するアイテムであり、データソース自体ではないため、返されたデータソース JSON オブジェクトは元のデータソースと非常によく似ています。添付ファイルを Excel (*.xlsx) ファイルとして解析できない場合には、400: Bad Request レスポンスが返されます。

dataSource クエリパラメーターは必須です。リクエストに dataSource クエリパラメーターが含まれていない場合には、400: Bad Request レスポンスが返されます。ユーザーに指定されたデータソースへのアクセス権限がない場合には、403: Forbidden レスポンスが返されます。

このエンドポイントは、指定されたデータソースを上書きします。つまり、上書きが完了すると、データソースのコレクションとコレクションの内容は、*.xlsx ファイルからの新しいデータソースの作成エンドポイントを使用してデータソースが作成されたかのように表示されます。指定したコレクションが削除、上書き、または作成されるかどうかは、古いコレクションの名前と新しいファイルのタブ名により異なります。このエンドポイントの呼び出し前に存在したものの、添付の Excel ファイルに一致するタブがないコレクションはすべて削除されます。添付の Excel ファイルのタブのいずれかに一致する名前がある既存のコレクションについては、内容は上書きされますが、コレクション ID 自体は変わりません。添付の Excel ファイルのタブのうち、既存のコレクション内に一致する名前がないものはすべて作成されます。このエンドポイントが呼び出されるたびにメタデータコレクションがゼロから作成される可能性がありますので注意してください。メタデータコレクション ID は保持されません。

メソッド : PUT

URI: https://data.app.(lucidchart/lucidpress).com/adapter/excel

クエリ文字列 :

dataSource: <DataSourceLink>

URI の例 : https://data.app.lucidchart.com/adapter/excel?dataSource=https://data.lucidchart.com/dataSources/134

ペイロード : Excel (*.xlsx) ファイルが添付されたマルチパートフォームデータ

戻り値 : データソース JSON オブジェクト

Google Sheets アダプター

メソッド : POST

URI: https://data.app.(lucidchart/lucidpress).com/adapter/googleSheets

クエリ文字列 :

  • permissionType (任意): データソースの許可の権限のタイプ ("account"、"user"、"document" のいずれか)、下位互換性のため既定では "user"

Google Sheets アダプターオブジェクト

{
    "docId": <String>,
    "sheets": Optional<[String]>,
    "name": Optional<String>,
    "dataSet": Optional<DataSetLink>
}

 

docId パラメーターは、データソースを添付する Google Sheets ドキュメントを指定します。sheets パラメーターが存在する場合には、指定された Google Sheets ドキュメントからインポートするタブのタイトルのリストを示します。 

 

特定の Google Sheets ドキュメントに接続されたデータソースの作成または更新

このエンドポイントは、指定された Google Sheets ドキュメントにリンクされているデータソースを作成、変更、または返します。データソース JSON オブジェクトが返されます。このエンドポイントには、Google Sheets アダプターオブジェクト (上記参照) が必要です。指定した Google Sheets ドキュメントのタブは、それぞれ個別のコレクションにインポートされます。sheets パラメーターが含まれていない場合、ドキュメントのすべてのタブがインポートされます。 

このエンドポイントは、ユーザーが Lucidchart に Google の認証情報を自ら提供し、Lucidchart に代理での Google Sheets へのアクセスを許可した場合にのみアクセスが可能です。また、このエンドポイントを使用してデータをインポートするには、指定した Google Sheets ドキュメントに個人的にアクセスできる権限が必要となります。 

指定した Google Sheets ドキュメントにリンクされたデータソースにユーザーがすでにアクセスした後にこのエンドポイントが呼び出された場合、このエンドポイントは、以下の通り、新しいデータソースを作成するのではなく、リンク済みのデータソースを更新します。

  • sheets パラメーターにまだリンクされていないシートがある場合、これに対応するリンク済みのコレクションが作成されます。
  • sheets パラメーターが存在せず、データソースの同期以降に Google Sheet ドキュメントに新しいタブが作成された場合は、これらの新しいタブに対応するコレクションが作成されます。
  • データソースの最後の同期以降にタブが削除された場合は、対応するコレクションが削除されます。