Skip to main content

This documentation is for an older version of this product. See the latest version of this content.Opens in a new tab

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

このページでは、一連の例を通じて InterSystems IRIS® のソース・コード・ファイル REST API の使用法を紹介する簡単なチュートリアルを提供します。

API の基礎

InterSystems IRIS のソース・コード・ファイルにアクセスするために Atelier で使用される API では、REST アーキテクチャ・スタイルが採用されています。REST は、"Representational State Transfer" の略です。InterSystems IRIS ソース・コード・ファイル 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/ - このチュートリアルでは、InterSystems IRIS がローカル・サーバ上でポート 52773 を使用して実行されていると想定しています。

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

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

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

    http://localhost:52773/api/atelier/v1/MYNS/docnames

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

    http://localhost:52773/api/atelier/

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

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

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

Note:

この API のエンドポイントには、用語 atelier があります。Eclipse ベースの IDE であり、インターシステムズでは非推奨になっている Atelier で使用する目的で、この API が開発されたからです。インターシステムズの VS Code - ObjectScript IDE では、現在この同じ API を使用しています。

InterSystems IRIS サーバに関する情報の取得

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

GET http://localhost:52773/api/atelier/

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

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": {
      "version": "IRIS for Windows (x86-64) 2018.1.1 (Build 515U) Mon Feb 5 2018 08:24:13 EST",
      "id": "98E1697E-13F9-4D6A-8B73-827873D1D61C",
      "api": 2,
      "features": [
...
      ],
      "namespaces": [
        "%SYS",
        "USER"
      ]
    }
    }
}

JSON メッセージを返すすべてのメソッドでは、以下のように同一の汎用フォーマットが使用されます。

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

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

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

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

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

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

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

  • api - このバージョンの InterSystems IRIS で実装されている InterSystems IRIS ソース・コード・ファイル REST API のバージョン番号が示されます。

  • features - このインスタンスで有効になっている機能を示します。

  • namespaces - InterSystems IRIS サーバ上で定義されたネームスペースがリストされます。

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

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

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

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

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

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

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

{
  "status": {
    "errors": [],
    "summary": ""
  },
  "console": [],
  "result": {
    "content": [
      {
        "name": "%Api.DocDB.cls",
        "cat": "CLS",
        "ts": "2016-08-03 20:01:42.000",
        "upd": true,
        "db": "IRISLIB",
        "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:52773/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:52773/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:52773/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:52773/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 メソッドは、任意の InterSystems IRIS データベースに対する SQL クエリを実行します。例えば、アプリケーションで InterSystems IRIS のロールをユーザに一覧表示するには、次の呼び出しを使用してそれらのロールを検出できます。

POST http://localhost:52773/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 メソッドを使用して、InterSystems IRIS 内の任意のテーブルに対してクエリを実行できます。例えば、次の呼び出しでは、SAMPLES というネームスペースの Sample.Person というテーブルがクエリされます。

POST http://localhost:52773/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 sectionソース・コード・ファイル REST API のリファレンス
Previous sectionInterSystems IRIS ソース・コード・ファイル REST API の概要
FeedbackOpens in a new tab