Skip to main content

This is documentation for Caché & Ensemble. See the InterSystems IRIS version of this content.Opens in a new tab

For information on migrating to InterSystems IRISOpens in a new tab, see Why Migrate to InterSystems IRIS?

Caché ソース・コード・ファイル REST API のチュートリアル

この章では、一連の例を通じて Caché ソース・コード・ファイル REST API の使用法を紹介する簡単なチュートリアルを提供します。このドキュメントの内容は次のとおりです。

API の基礎

Caché のソース・コード・ファイルにアクセスするために Atelier で使用される API では、REST アーキテクチャ・スタイルが採用されています。REST は、"Representational State Transfer" の略です。Caché ソース・コード・ファイル REST API では、多くの REST API と同様に、HTTP GET、POST、PUT、DELETE、および HEAD の各メソッドを使用します。また、受信/送信メッセージの本文には JSON を使用します。

API メソッドを呼び出すには、以下について知っておく必要があります。

  • HTTP メソッド - GET、POSfT、PUT、DELETE、または HEAD のいずれかです。

  • HTTP ヘッダ - 呼び出しのコンテキスト情報を提供します。この API で使用されるヘッダは次のとおりです。

    • 認証：サーバへのアクセスを可能にします。サーバを最小限のセキュリティでインストールしている場合を除いて、この API にアクセスするためにはユーザ名とパスワードを入力する必要があります。

    • Content-Type application/json：インバウンド・ペイロードが JSON で提供されていることを指定します。このヘッダは、すべての POST メソッドと PUT メソッドについて指定する必要があります。

    • If-None-Match：ソース・コード・ファイルが前回のアクセス以降に変更されたかどうかを GetDoc または PutDoc 呼び出しによって確認できるようにします。

  • URL - URL は以下の要素で構成されています。

    • http://

    • server-name:port-number/ - この章では、Caché がローカル・サーバ上で実行されており、ポート 57772 を使用していると想定しています。

    • api/atelier/ - これは、%Api.AtelierOpens in a new tab ディスパッチ・クラスを持つ Web アプリケーションによって定義されます。

    • メソッドとターゲットを識別する URL 要素。この要素には、固定テキストを含めることができると共に、ネームスペース、ドキュメント名、またはタイプを特定するために指定するテキストを含めることができます。

    例えば、GetDocNames メソッドを識別する URL 要素は v1/namespace/docs/ です。SAMPLES ネームスペースからドキュメントを取得するこのメソッドの完全な URL は次のようになります。

    http://localhost:57772/api/atelier/v1/SAMPLES/docnames

    この URL 要素では、GetServer メソッドが空の文字列であることが指定されるため、GetServer の完全な URL は次のとおりです。

    http://localhost:57772/api/atelier/

  • URL パラメータ - 呼び出しに変更を加えます。この API のメソッドで指定できる URL パラメータについては、リファレンスのセクションで説明しています。

  • インバウンド JSON ペイロード - POST メソッドと PUT メソッドのインバウンド・メッセージのフォーマット。

  • アウトバウンド JSON ペイロード - HTTP メソッドによって返されるアウトバウンド・メッセージのフォーマット。

Caché サーバに関する情報の取得

通常、最初に発行する REST 呼び出しは GetServer メソッドの呼び出しです。このメソッドは、Caché ソース・コード・ファイル REST API のバージョン番号およびサーバ上で使用可能なネームスペースに関する情報を返します。

GET http://localhost:57772/api/atelier/

この呼び出しは、以下の JSON メッセージを返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "version": "Cache for Windows (x86-64) 2017.2 (Build 691U) Wed Jun 7 2017 20:45:20 EDT",
      "id": "B70A630D-A34D-43B1-8EA5-EDF8F38992C4",
      "api": 2,
      "features": [
        {
          "name": "DEEPSEE",
          "enabled": true
        },
        {
          "name": "ENSEMBLE",
          "enabled": true
        },
        {
          "name": "HEALTHSHARE",
          "enabled": false
        }
      ],
      "namespaces": [
        "%SYS",
        "DOCBOOK",
        "ENSDEMO",
        "ENSEMBLE",
        "INVENTORY",
        "SAMPLES",
        "USER"
      ]
    }
  }
}

JSON メッセージを返すすべての Caché ソース・コード・ファイル REST API メソッドでは、以下に示す同一の汎用フォーマットが使用されます。

  • status errors - Caché ソース・コード・ファイル REST API は、通常、エラーを HTTP ステータス・コードとして返します。このフィールドはいくつかの特殊な状況で使用され、この要素には Caché の %Status 値が含まれており、この値には複数のエラーのテキストが含まれていることがあります。

  • status summary - ステータス・エラーの要約情報が含まれています。

  • console - この操作について Caché によってコンソールに表示されるテキストが含まれています。

  • result - そのメソッドの結果が含まれています。

GetServer メソッドは、サーバに関する情報を “result” 要素内に返します。result 要素には “content” という 1 つの値が含まれており、この値には以下が含まれています。

  • version - サーバ上で実行されている Caché または Ensemble のインスタンスのバージョン文字列が含まれています。

  • id - Caché のインスタンス GUID が含まれています。

  • api - このバージョンの Caché で実装されている Caché ソース・コード・ファイル REST API のバージョン番号が示されます。Caché 2016.2 と2017.1 では、このバージョンは 1 です。Caché 2017.2 では、このバージョンは 2 です。この要素内に返されたバージョンが 3 以上の場合は、追加の API が呼び出し可能になります。

  • features - DEEPSEE、ENSEMBLE、HEALTHSHARE などの機能がこのインスタンス上で有効になっているかどうかを示します。

  • namespaces - Caché サーバ上で定義されたネームスペースが列挙されます。

GetNamespace メソッドは、指定されたネームスペースに関する情報を返します。この情報には、そのネームスペースにマップされたデータベース、および各データベースのハッシュが含まれます。このハッシュは、サーバとの通信の効率を高めるのに役立ちます。ただし、GetServer によって返されるネームスペース情報のみを含めて、そのネームスペース内のソース・コード・ファイルに関する情報を取得できます。

ネームスペース内で定義されたソース・コード・ファイルの取得

ネームスペース内のソース・コード・ファイルに関する情報を取得する手順は次のとおりです。

  • 最初に、GetDocNames メソッドを使用してそれらのファイルの名前を取得します。

  • 次に、GetDoc メソッドを使用して単一ファイルのコンテンツを取得するか、GetDocs メソッドを使用して複数ファイルのコンテンツを取得します。

  • お使いのアプリケーションのネットワーク効率を高めるために、ソース・コード・ファイルの名前とコンテンツのローカル・キャッシュを保持しておいて、GetModifiedDocNames メソッドを使用して、コンテンツが変更されたソース・コード・ファイルの名前のみを取得することも、If-None-Match HTTP ヘッダを指定して GetDoc メソッドを使用することもできます。

GetDocNames メソッドは、指定されたネームスペースにマップされたすべてのデータベース内のすべてのソース・コード・ファイルの名前を返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "name": "%Activate.Enum.cls",
        "cat": "CLS",
        "ts": "2016-08-03 20:01:42.000",
        "upd": true,
        "db": "CACHELIB",
        "gen": false
      },
      ...
      {
        "name": "EnsProfile.mac",
        "cat": "RTN",
        "ts": "2003-09-19 13:53:31.000",
        "upd": true,
        "db": "INVENTORYR",
        "gen": false
      },
      ...
      {
        "name": "xyz.mac",
        "cat": "RTN",
        "ts": "2016-08-11 15:05:02.167",
        "upd": false,
        "db": "INVENTORYR",
        "gen": false
      }
    ]
  }
}

次の GetDoc 呼び出しは xyz.mac ファイルのコンテンツを返します。

http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac

この呼び出しは以下を返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "2016-09-14 14:10:16.540",
    "upd": false,
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": [
      "ROUTINE xyz",
      "xyz ;",
      "   w \"hello\""
    ]
  }
}

ネームスペース内の新規ファイルの作成または既存ファイルの更新

ネームスペース内で新規ファイルを作成するか、既存のファイルを更新するには、PutDoc メソッドを使用します。例えば、次の REST 呼び出しは、新しい xyz.mac ソース・コード・ファイルを INVENTORY ネームスペース内に作成するか、xyz.mac ファイルが存在する場合は、このファイルの元の定義を新しい定義に置き換えます。新しいファイルを更新する場合は、HTTP ヘッダ If-None-Match を指定してファイルの現在のバージョンを特定するか、?ignoreConflict=1 URL パラメータを指定してバージョン確認を省略する必要があります。詳細は、リファレンス・セクションの "PutDoc" を参照してください。

PUT http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac

Content-Type application/json と次の JSON メッセージを指定する必要があります。

{
 "enc": false,
 "content": [
   "ROUTINE xyz",
   "xyz ;",
   "   w \"hello\""
   ]
}

この呼び出しは、以下の JSON メッセージを返します。このメッセージは、このソース・コード・ファイルが INVENTORYR データベース内に作成されたことを示しています。このデータベースは、INVENTORY ネームスペース内のルーチンの既定データベースです。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "2016-09-14 14:10:16.540",
    "upd": false,
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": []
  }
}

バイナリ・ファイルを更新または作成する場合は、enc に true という値を指定して、バイナリ値の base64 エンコーディングのブロックの配列としてバイナリ・コンテンツを含めます。

ファイルのコンパイル

Compile メソッドは、受信 JSON 配列内の名前によって指定されたソース・コード・ファイルをコンパイルします。例えば、xyz.mac をコンパイルするには、以下を POST します。

http://localhost:57772/api/atelier/v1/INVENTORY/action/compile

この際に、次の JSON メッセージを含めます。

["xyz.mac"]

このメソッドは以下を返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [
    "",
    "Compilation started on 08/14/2016 15:25:20 with qualifiers 'cuk'",
    "xyz.int is up to date. Compile of this item skipped.",
    "Compilation finished successfully in 0.008s."
  ],
  "result": {
    "content": []
  }
}

クラスなどの一部のソース・コード・ファイルの場合は、Compile メソッドは返されるコンテンツ内に保管情報を返します。

ファイルの削除

DeleteDoc メソッドは、URL で指定されたファイルを削除します。DeleteDoc メソッドの URL は GetDoc メソッドと同じですが、唯一の相違点として、Get メソッドの代わりに HTTP Delete メソッドを使用します。xyz.mac を削除するには、次の URL を使用して HTTP DELETE 要求を発行します。

http://localhost:57772/api/atelier/v1/INVENTORY/doc/xyz.mac

この Delete メソッドは、以下の JSON メッセージを返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "name": "xyz.mac",
    "db": "INVENTORYR",
    "ts": "",
    "cat": "RTN",
    "status": "",
    "enc": false,
    "flags": 0,
    "content": []
  }
}

ファイルが削除されると、タイムスタンプ ts の値は "" (空の文字列) になります。

SQL クエリの実行

Query メソッドは、任意の Caché データベースに対する SQL クエリを実行します。例えば、お使いのアプリケーションが Caché のロールをユーザに一覧表示しようとする場合は、次の呼び出しを使用してそれらのロールを検出できます。

POST http://localhost:57772/api/atelier/v1/%25SYS/action/query

この際に、受信 JSON メッセージ内で指定された SQL クエリを使用します。

{"query": "SELECT ID,Description FROM Security.Roles"}

この呼び出しは、SQL クエリの結果を JSON 形式で result content 要素内に返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "ID": "%all",
        "Description": "The Super-User Role"
      },
      {
        "ID": "%db_%default",
        "Description": "R/W access for this resource"
      },
      ... 
      {
        "ID": "%sqltunetable",
        "Description": "Role for use by tunetable to sample tables irrespective of row level security"
      }
    ]
  }
}

Query メソッドを使用して、Caché 内の任意のテーブルに対してクエリを実行できます。次の呼び出しは、SAMPLES ネームスペース内の Sample.Person データベースに対してクエリを実行します。

POST http://localhost:57772/api/atelier/v1/SAMPLES/action/query
{"query": "SELECT Age,SSN,Home_City,Name FROM Sample.Person WHERE Age = 25"}

この呼び出しは以下を返します。

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "Age": 25,
        "SSN": "230-78-7696",
        "Home_City": "Larchmont",
        "Name": "DeLillo,Jose F."
      },
      {
        "Age": 25,
        "SSN": "546-73-7513",
        "Home_City": "Gansevoort",
        "Name": "Klingman,Thelma H."
      }
    ]
  }
}
Next sectionCaché ソース・コード・ファイル REST API のリファレンス
Previous sectionCaché ソース・コード・ファイル REST API の概要
FeedbackOpens in a new tab