API Connector

Version 21.0.8222


API Connector


The API Connector supports publishing custom API’s at an ArcESB endpoint. If you are looking for an API client to consume APIs, use the REST Connector instead.

概要

The API Connector exposes tables, views, and stored procedures from a database as a web API. The API Connector reads the available tables, views, and stored procedures from the target database, then any subset of these can be exposed as API resources.

API Connectors can also be used to expose a custom scripting endpoint. When an API call is made to a custom script, the script is executed to build the API response. Custom scripting is an extremely flexible approach to providing Arc resources as responses to web requests.

Connector Configuration

This section contains all of the configurable connector properties.

Connection Tab

Configuration

Settings that determine how the API can be accessed.

  • Connector Id The static name of the connector. All connector-specific files are held in a folder by the same name within the Data Directory.
  • Connector Description An optional field to provide free-form description of the connector and its role in the flow.
  • API エンドポイント The URL at which the custom API will be published. To access a specific resource, append a slash and the resource name to this URL value.
  • API ドキュメント The URL at which the documentation for the custom API will be published.

Connection

Settings related to the database connection.

  • データソースの種類 The type of database to connect to.
  • 設定フォーマット Whether to specify a set of individual connection properties or a single connection string containing each of the properties.
  • 接続文字列 The database credentials in connection string format. Only applicable when 設定フォーマット is set to Connection String.
  • サーバー The host name or IP address of the server hosting the database.
  • ポート The port on which to connect to the database host.
  • データベース The name of the database to connect to.
  • ユーザー The user credential that has permission to access the database.
  • パスワード The password credential associated with the specified ユーザー.

Advanced Section

Advanced settings are auto-generated based on the configured データソースの種類. For more information on an advanced setting, please see the documentation for the connector that matches the data source (e.g. please see the MySQL Connector documentation for advanced settings when the データソースの種類 is MySQL).

Other Settings

Settings that do not fall into the previous categories.

  • Log Subfolder Scheme Instructs the connector to group files in the Logs folder according to the selected interval. For example, the Weekly option instructs the connector to create a new subfolder each week and store all logs for the week in that folder. The blank setting tells the connector to save all logs directly in the Logs folder. For connectors that process many transactions, using subfolders can help keep logs organized and improve performance.
  • Log Messages Whether the log entry for a processed file will include a copy of the file itself.
  • Save to Sent Folder Whether files processed by the connector should be copied to the Sent folder for the connector.

Miscellaneous

Settings for specific use cases.

  • Other Settings Allows configuration of hidden connector settings in a semicolon-separated list, like setting1=value1;setting2=value2. Normal connector use cases and functionality should not require use of these settings.

Resources Tab

Resources

The list of API resources exposed by the connector. Each Resource is generated from a table or view present in the connected database. Adding a new resource exposes new database data to a web API call via the connector.

Actions Tab

Actions

The list of API actions exposed by the connector. Each Action is generated from a stored procedure present in the connected database. Adding a new action exposes new database data to a web API call via the connector.

Users Tab

Users

The list of users authorized to make API calls to the connector. Users can be restricted by HTTP method (GET, POST, etc), number of requests per hour, and number of concurrent requests. API credentials can also be managed on a by-server basis in the Server tab.

Server Tab

Trusted IP Addresses

This section defines the IP addresses that are allowed to make connections. The following functions are available:

  • Add Opens a modal to enter a new IP address range.
  • Edit Opens a modal to modify the selected IP address range.
  • Delete Deletes the selected IP address range from the list.

The following restrictions apply to this feature:

  • localhost cannot be modified or removed from the list.
  • Any IP addresses outside of the defined ranges will be rejected.
  • Ranges are supported. For example, the entry 100.10.100.1-15 indicates that IP addresses between 100.10.100.1 and 100.10.100.15 are allowed.
  • CIDR notation is supported. For example, the entry 100.10.100.0/24 indicates that IP addresses between 100.10.100.0 and 100.10.100.255 are allowed.
  • Wildcard patterns are supported. For example, the entry 100.10.100.* indicates that IP addresses beginning with 100.10.100 are allowed.

Default Rate Limits (Per User)

Settings restricting the number of API requests allowed.

  • 1時間あたりの最大リクエスト数 The limit to the number of requests a single user can issue in an hour.
  • Max Concurrent Requests The limit to the number of concurrent requests a user can issue.

Cross-Origin Resource Sharing (CORS)

Settings governing the use of CORS to serve cross-origin resources.

  • クロスオリジンリソースシェアリング(CORS)を有効化する Whether or not CORS is enabled.
  • すべてのドメインを’*’ なしで許可 If enabled, domain origins will not be restricted to a specific list.
  • Access-Control-Allow-Origin The comma-delimited list of domain origins to allow. Included as an HTTP response header.
  • Access-Control-Allow-Credentials Whether or not user credentials such as cookies are allowed in cross-origin requests. Included as an HTTP response header.
  • Access-Control-Allow-Methods The comma-delimited list of methods to allow. Included as an HTTP response header.
  • Access-Control-Allow-Headers The comma-delimited list of headers to allow. Included as an HTTP response header.
  • Access-Control-Max-Age The maximum duration that Access-Control response header values can be cached.

OData

Settings related to OData feature support.

  • Server-Side Paging Size The number of results per-page returned by an OData request. All results will be returned when this option is set to 0.
  • デフォルトフォーマット The OData format to be used when the client does not specify a format.
  • デフォルトバージョン The OData version to be used when the client does not specify a format.
  • Date Time Format The format to use when returning date-time information.
  • ベースURL The fully qualified URL of the OData endpoint. If unspecified, Arc will attempt to create the base URL based on the incoming request.

Establishing a Connection

Before creating your first API, you need to connect to your data store. Arc supports connecting to relational databases, file stores, and back-end services such as other APIs.

Once you select the data store type on the connection page, a list of connection properties is generated for the selected data store. Enter your credentials for connecting to the data store and save your changes on this page. Click 接続テスト to make sure the app is connected to your data store.

Note: The application includes drivers for some common databases, but may not include drivers for all the data sources it supports. For drivers that are not included, make sure to follow the instructions below for your machine type.

Windows 版

Install the ADO.NET provider on this machine, restart the server, and retry connecting to your data store.

Java 版

Java Web サーバーのlib フォルダにJDBC ドライバーをコピーします。

Building Your First API

データソースへの接続を定義した後に、API のリソースの公開方法を決定します。You can use the wizard in the administration console to generate schemas for reading and writing to your data store.

Surfacing Database Resources

To use the wizard to model a database as an API:

  1. Click Resources > Add Resource.
  2. Select a table you want to model as an API.
  3. リソースの中からAPI として公開するカラムを選択します。

The resource is defined in a schema, which can easily be modified or extended without regenerating from the database. You can modify the schema by clicking the resource or ** in the entry for the resource. The generated schema contains the two essential components of a schema:

  • An info block containing resource columns definitions
  • HTTP メソッドに対応するメソッド、およびデータプロセスオペレーションを呼び出すメソッド

Querying Your API

API のリソースを作成後、API を権限を持つユーザーおよびIP アドレスに対して公開できます。Arc uses auth token-based authentication and supports the major authentication schemes. Click the ユーザー tab to manage auth tokens and permissions for users. To define the IP addresses allowed to access the application, click the Server tab.

You can now query your API in the browser, as shown in the example query and response below.

リクエスト

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

レスポンス

{ 
  "@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value":[
    { "Id": "10001", "Model": "MyModel1", "Color": "Red" },
    { "Id": "10002", "Model": "MyModel2", "Color2": "Blue" },
  ]
}

API Management

Arc enables you to create and manage an API that allows integration with other applications. This API contains Web services that are secure and remotely accessible from any application, browser, or smart device. The resources in this API use JSON-formatted OData as the default REST protocol for accessing data. Other Web service formats are supported, including OData (Atom), JSONP, HTML, and CSV.

You can browse your APIs and manage access to them in the administration console. Click API on the navigation bar to view documentation and examples of accessing the API. Go to the application settings to manage your connection settings, resources, users, and server settings for your API.

This section contains topics related to designing and managing your API.

API Resources

リソースはAPI で公開されているオブジェクトで、クエリ、作成、更新、および削除が可能です。リソースは、作成、読み出し、更新、および削除(CRUD)操作の全範囲をサポートすることも、一部のみに限定することもできます。This section describes the HTTP methods used to perform CRUD operations on resources exposed by the application.

GET

HTTP GET リクエストは、サーバーからリソースまたはリソースセットを取得する場合に使用します。以下は、コレクション全体に対するリクエストの例です。

GET http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

以下は対応するレスポンスです。

{
  "@odata.context": "http://localhost:8153/api.rsc/$metadata#Products",
  "value": [
    { "Id":"Id_1", "Color":"Color_1", "Model":"Model_1"},
    { "Id":"Id_2", "Color":"Color_2", "Model":"Model_2"},
    { "Id":"Id_3", "Color":"Color_3", "Model":"Model_3"}
  ]
}

POST

HTTP POST リクエストは、リソース内に新規リソースを作成する場合に使用します。リクエストは、新しいリソースを作成するために必要なインプットを含んでいなければなりません。次にリクエストの例を示します。

POST http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars
{
  "Color": "Color_1", "Model": "Model_1" 
}

以下は対応するレスポンスです。

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
	"value": [
		{ "Color": "Color_1", "Model": "Model_2" }
	]
}

PUT

HTTP PUT リクエストは、リソースを更新する場合に使用します。主キーが必要です。次にリクエストの例を示します。

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('Id_1')
{
  "Color": "Color_1", "Model": "Model_1"
}

以下は対応するレスポンスです。

{
	"@odata.context":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars/$entity",  
	"Id": "Id_1", "Color": "Color_1", "Model": "Model_1"
}

DELETE

HTTP DELETE リクエストは、リソースを削除する場合に使用します。主キーが必要です。次にリクエストの例を示します。

DELETE http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/('Id_1')

The response is empty with a 204 No Content HTTP status line.

Overriding HTTP Methods

クライアントのいくつかは、特定の処理のための正しいHTTP メソッドを発行することができないかもしれません。You can use the @x-http-method query string input parameter or the X-HTTP-Method HTTP header to override the HTTP method for a request. For example, a client that does not support the HTTP PUT method can include the X-HTTP-Method:PUT header with a GET request to issue an update request for a resource.

Filtering Resources

HTTP GET リクエストを使用して、すべてのリソースの取得、リソースのフィルタリング、リソースのソート、およびリソースから返されるデータの制限が可能です。URL のパスは、取得するリソースのセットを指定します。例えば、すべてのCars リソースを取得するには、次のURL を使用します。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars

Single Resource

1つのリソースを取得するには、そのリソースのURL に対してリクエストを投げます。URL を作成するには、目的のリソースの主キーを使用します。例:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')

リソースによっては、次の例に示すような索引付きの複数の主キーがある場合があります。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars(Id='1000', Date='2016-07-01')

Filtering

クライアントアプリケーションは、リクエスト内で提供されるフィルタを元に、複数のリソースを取得することができます。例としては、Make が’Honda’ にマッチするすべてのリソースを取得するフィルタは、次のようになります:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda'

The application supports the following logic operators for comparison:

Eq イコール
Ne イコールではない
Gt 大なり
Ge 大なりイコール
Lt 小なり
Le 小なりイコール
Not 否定

You can also use and and or to combine multiple filters:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=Make eq 'Honda' and Date lt '2016-07-01'

The startswith, endswith, toupper, tolower, and contains functions can be used with the $filter query option.例えば、次のリクエストは、指定されたサブ文字列を含むプロパティのリソースを返します。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$filter=contains(Make,'Honda')

Selecting Properties

To retrieve a subset of properties, use $select, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$select=Id,Model

これは、リクエスト内のフィルタにマッチするすべてのリソースのId およびModel プロパティを返します。

また、次の例に示すように1つのリソースの個別のプロパティ値を取得することも可能です。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')/Model/$value

Sorting

You can use $orderby to sort resources, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$orderby=Model asc, Color desc

これは、Model(昇順)、そしてColor(降順)で並べ替えられたリソースを返します。

Pagination

Server-Side

The application supports server-side paging, which can be enabled in the Settings > Server section of the application. When the page-size is greater than 0 and a request returns results larger than the page size, the URL for the next page of results is included in the @odata.nextlink attribute of the response.結果の最後のページにはこの属性は含まれません。このURL には、2分間有効なページングトークンが含まれています。例えば、次のレスポンスは3つのリソースを持ち、@odata.nextLink 属性はレコードの次のページのURL を含んでいます。

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$skiptoken=0f87696b-aa28-4a70-b13d-c86af8338c80"
}

Client-Side

The Arc also supports client-side paging using $top, $skip, and $count.

You can use $top=n to include only the first n resources in the result.例えば、次の要求を使用すると、上位10個のCars リソースを表示できます。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10

You can use $skip=n to exclude the first n resources from the result. You can use $top with $skip to implement client-side paging. $skip is always applied before $top, regardless of their order in the query.例えば、次の2つのクエリは、最初の20個の リソースを2ページに分けて取得します:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10 http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=10&$skip=10

You can also set the parameter $count to true to return the total number of records in the results. If using OData version 2.0 or 3.0, you can set $inlinecount to allpages instead.例えば、次のクエリを考えてみましょう:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$top=3&$skip=4&$count=true

このクエリは、次のようなレスポンスを返します:

{
  "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
  "@odata.count": 402,
	"value": [
    { "Id": "Id_1", "Color": "Color_1", "Model": "Model_1"},
    { "Id": "Id_2", "Color": "Color_2", "Model": "Model_2"},
    { "Id": "Id_3", "Color": "Color_3", "Model": "Model_3"}
  ],
  "@odata.nextLink":"http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Account?$skip=7"
}

このように、フィルタにマッチする合計カウントが、結果のシングルページと共にレスポンスで返されます。

Count-Only

次の例に示すように、クエリの特定のフィルタにマッチするリソースのカウントのみを取得することができます。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$count=true&$filter=Make eq 'Honda'

レスポンスは、リクエストのフィルタにマッチするリソースの行カウントになります。

API Actions

アクションはリソースに対する処理セットを拡張する場合やサーバーで関連のないアクションを実行する場合に使用します。アクションはHTTP POST リクエストとして実行されなければなりません。次にアクションの実施の例を示します。

POST http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/WashCar/
{
  Wax: "Wax_1"
}

以下は対応するレスポンスです。

{"Complete": "Complete_1"} 

Use URL Parameters as Input

In cases where the client does not support the HTTP POST method, the Action can be invoked using the URL parameters @x-http-method. Action のインプットは、追加のURL パラメータとして指定できます。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/WashCar?@x-http-method=POST&URLparam1=my\_url\_parameter1&urlparam2=my\_url\_param2

Discovery

Based on the OpenAPI specification, the application’s APIs are fully documented and discoverable. API には、標準のJavaScript、OpenAPI 準拠のアプリケーション、またはOData 標準をサポートするアプリケーションからアクセスできます。次のセクションではこれらのスタンダードを使用してAPI を検出する方法について説明します。

Service Document

サービスドキュメントはデフォルトで、JSON 形式のすべてのAPI の単純なリストです。サービスドキュメントは、メタデータ検出リクエストを含むすべてのリクエストが生成されるサービスルートから返されます。次に、サービスルートの例を示します。

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/

より詳細な情報を取得するには、メタデータURL にリクエストを投げます。

Metadata URL

The application exposes the capabilities of its APIs to OData consumers through the OData metadata document URL.メタデータドキュメントは、XML で返され、カラムのデータ型、リソースのキー、および他の情報を含みます。You can access the complete metadata resource by appending $metadata to the service root, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata

To access the metadata for a resource, append $metadata to the resource URL of the resource:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/$metadata

OpenAPI Definition

OpenAPI (Swagger) definitions are generated for the data sources you surface through the application.

To obtain the Swagger definition, append $swagger to the service root, as shown in the following example:

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$swagger

Server Responses

次は、API リソースに対する代表的なサーバーレスポンスのリスト、およびいつそのようなレスポンスが返されるかの説明です。

200 OK リクエストはエラーなしでサーバーにより処理されました。
201 Created リクエストは成功し、指定されたものがサーバーによって作成されました。
204 No Content リクエストされたリソースがnull 値もしくは、サービスがreturn=minimal preference が適用される場合、リクエストはこのステータスを返します。
400 Bad Request リクエストは受付できないか、必要なパラメータを満たしていません。
401 Unauthorized このユーザーは認証されていないか、このリソースへのアクセスが承認されていません。
403 Forbidden このリソースへのアクセスが拒否されました。
404 Not Found リソースが存在しません。
405 Method Not Allowed 指定されたHTTP メソッドはこのリソースでは許可されていません。
429 Too Many Requests ユーザーが指定した時間内に送信したリクエストが多すぎるか、同時リクエストの最大数を超えました。
501 Not Implemented サーバーは、リクエストを充足する機能をサポートしていません。このレスポンスは、サーバーがリクエストメソッドを認識しないときで、存在するリソースではサポートすることができない場合に返されます。

Users

Arc uses auth token-based authentication to control per-user access to the API.auth トークンは、ユーザーがAPI に認証をするためのランダムに生成されたユニークな識別子です。auth トークンはユーザーの現在の権限を表します。

auth トークンは、主要な認証スキームを使って接続することを可能にします。例えば、HTTP ベース認証を使用するには、User ヘッダーにユーザー名を、そしてPassword ヘッダーにユーザーの対応する認証トークンを設定します。See Authentication for more information on authenticating to the API.

Adding Users

To add a user, navigate to the ユーザー tab for the connector, and click **.ダイアログが表示されたら、以下の情報を入力します。

  • 名前:HTTP 認証で使われるユーザー名を入力します。
  • 権限:GET、POST、PUT/PATCH/MERGE、もしくはDELETE からユーザーがアクセスを認められているHTTP メソッドを選択します。これらは、SELECT、INSERT、UPDATE、およびDELETE にそれぞれ対応します。
  • Max. Requests:このユーザーの一時間毎の最大リクエスト数を入力します。0 の値は、そのユーザーの時間ごとのアクセス数が無制限となります。
  • Max. Concurrent Requests:同時に送信可能なリクエストの最大数を入力。0 の値は、そのユーザーの同時リクエスト数が無制限となります。

Note that user-specific settings override server-wide API limit settings. An empty value for one of the user settings uses the server default.

Configuring the User Database

Arc stores user information in an SQLite database by default.ユーザー情報を保存するデータベースを自分で選択することもできます。組み込みサーバーを使っている場合には、Web コンフィギュレーションの接続文字列エレメントでキャッシュデータベースの接続文字列を指定します。Otherwise, refer to the documentation for the server you are hosting the application on.

Authentication

Users access API resources by providing auth tokens with requests. You can manage users and auth tokens on the Users tab of the API Connector settings pane.

Before users can call the API, you also need to set trusted IP addresses for connections. These settings are available on the Server tab of the API Connector settings pane. By default, all IP addresses are restricted.

Using Auth Tokens in Basic Authentication

Enter the user’s auth token as the password when using Basic Authentication.

Using Auth tokens in the HTTP Header

Add the HTTP header x-arcesb-authtoken with the desired auth token as part of the HTTP request.

Using Auth Tokens as Query String Parameters

To allow the connector to pass the auth token in query string parameters, open the Server tab of the API Connector settings pane and select Allow authtoken in URL in the Advanced Settings section.

After enabling this feature, you can specify the auth token as the value of the @authtoken parameter, which can be supplied as part of the HTTP form-post data or a query parameter.

Rate Limiting

ユーザーごとの制限、およびサーバー全体のデフォルト制限の両方を設定することができます。

Server Defaults

To configure the default rate limits applied to all users, navigate to the Server tab for the connector.このページで、次のオプションが設定できます。

  • Max.時間ごとのリクエスト数時間ごと、ユーザーごとに許可されるデフォルトの最大のリクエスト数。0 の値は時間ごとのリクエスト数がデフォルトで無制限となります。
  • Max.コンカーレントリクエスト:ユーザーごとに許可されるデフォルトの同時リクエスト数。0 の値は同時に出せるリクエスト数がデフォルトで無制限となります。

User-Specific Limits

To configure rate limits for an individual user, navigate to the User tab for the connector, select a user, and click Edit.このダイアログで、次のオプションが設定できます。

  • Privileges:GET、POST、PUT/PATCH/MERGE、もしくはDELETE からユーザーがアクセスを認められているHTTP メソッドを選択します。これらは、SELECT、INSERT、UPDATE、およびDELETE にそれぞれ対応します。
  • Max. Requests (hr):このユーザーの一時間毎の最大リクエスト数を入力。0 の値は、そのユーザーの時間ごとのリクエスト数が無制限となります。
  • Max. Concurrent:このユーザーに許容された同時リクエスト数を入力。0 の値は、そのユーザーの同時リクエスト数が無制限となります。

ユーザー固有のレート制限はサーバーのデフォルト制限に優先します。ユーザー固有の設定に、空白がある場合にはサーバーのデフォルト制限が適用されます。

CORS

You can configure cross-origin resource sharing (CORS) on the Server tab.CORS allows browser-based clients to connect to Arc. Without CORS, browser-based scripts cannot connect to Arc because of the same-origin policy enforced by the browser.このポリシーは、クライアントサイドスクリプトおよびドキュメントが、自身のオリジン以外のリソースをロードすることを制限します。スクリプトのオリジンは、プロトコル、ホスト、およびポートから成ります。

When the option to enable CORS is selected, you can set the following options to configure CORS:

  • Allow all domains without *:When this option is set, the application allows any origin passed by the client by returning that origin in the Access-Control-Allow-Origin header.
  • Access-Control-Allow-Origin:Enter the origins for which the application will participate in CORS. The application returns these origins in the Access-Control-Allow-Origin header. When this is set to ‘’, the application allows any origin and pass ‘’ in the Access-Control-Allow-Origin header.これは公開API に適しています。

    When this is set to *, the application will allow any origin and pass * in the Access-Control-Allow-Origin header.これは公開API に適しています。

  • Access-Control-Allow-Methods:カンマ区切りで許容されるメソッドのリストを入力します。
  • Access-Control-Allow-Headers:スクリプトにより作成されたリクエストにおいて使用できるヘッダーのリストをカンマ区切りで入力します。
  • Access-Control-Allow-Credentials:クライアントにクレデンシャルを要求する場合には、これをtrue に設定します。
  • Access-Control-Max-Age:ユーザーエージェントがpreflight リクエストをキャッシュできる秒数を入力します。

Additional Output Formats

In addition to the default JSON format that all resources and actions support, the API also supports the following formats: XML, JSONP, RSS, HTML, CSV, and TSV.

XML

$format=atom クエリパラメータを追加するか、もしくはリクエストにapplication/xml という値を持つHTTP Accept ヘッダーを追加することで、XML (OData・Atom)形式をリクエストできます。次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$format=atom

Response

<?xml version="1.0" encoding="UTF-8"?>
<feed xmlns="http://www.w3.org/2005/Atom" xml:base="http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/" xmlns:m="http://docs.oasis-open.org/odata/ns/metadata" xmlns:info="http://www.arcesb.com/ns?RsbOps/v2/" xmlns:d="http://docs.oasis-open.org/odata/ns/data">
  <title type="text">Cars</title>
  <id>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars/</id>
  <updated>2015-04-23T18:36:20-04:00</updated>
  <entry>
  <title>1000</title><id>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000')</id>
  <category term="ArcESB.Cars" scheme="http://docs.oasis-open.org/odata/ns/scheme" />
  <link rel="edit" title="Cars" href="Cars('1000')"/>
  <content type="application/xml">
    <m:properties>
      <d:Id m:type="String">1000</d:Id>
      <d:Model m:type="String">Accord</d:Model>
    </m:properties>
  </content>
  </entry>
</feed>

JSONP

You can request the JSONP format by adding the $callback=myCallback query parameter, “where myCallback is the name of the function you would like to wrap the JSON result.次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?$callback=myCallback

Response

myCallback(
  {
    "@odata.context": "http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/$metadata#Cars",
    "value": [
      {
        "Id": "1000", 
        "Model": "Accord"
      },
      ...
    ]
  }
);

RSS

You can request the RSS format by adding the query parameter @rss to the request.次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@rss

Response

<rss xmlns:arc="http://www.arcesb.com/ns?RsbOps/v2/" xmlns:ls="http://www.microsoft.com/schemas/rss/core/2005" xmlns:dc="http://purl.org/dc/elements/1.1/" xmlns:x="http://www.arcesb.com/ns?RsbOps/v2/anonymous/" xmlns:odata="http://www.arcesb.com/ns?RsbOps/v2/anonymous/" xmlns:info="http://www.arcesb.com/ns?RsbOps/v2/anonymous/" xmlns:data="http://www.arcesb.com/ns?RsbOps/v2/anonymous/" version="2.0">
  <channel>
    <description>Retrieves and updates Cars information</description>
    <generator>Arc - http://www.arcesb.com</generator>
    <link>http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@html</link>
    <title>Cars</title>
    <item xmlns:x="http://www.arcesb.com/ns?RsbOps/v2/anonymous/">
      <x:Id>1000</x:Id>
      <x:Model>Accord</x:Model>
    </item>
  </channel>
</rss>

HTML

You can request the API response to be formatted as a simple, unstyled HTML table by adding the query parameter @html to the request.次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@html

Response

<table>
  <tr><th>Id</th><th>Model</th></tr>
  <tr><td>1000</td><td>Accord</td></tr>

CSV

You can request the API response to be formatted as CSV data by adding the query parameter @csv to the request.次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@csv

Response

Id,Model
1000,Accord

TSV

You can request the API response to be formatted as TSV data by adding the query parameter @tsv to the request.次のリクエストとレスポンスの例を参照してください。

Request

http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars?@tsv

Response

Id  Model
1000 Accord

Customizing Your API

Arc includes a wizard for building APIs based on tables in your database. The wizard can be accessed from the リソース tab.多くのデータベースがサポートされています。

API のリソースは、容易に拡張が可能なテキストベースのスキーマで定義されます。To edit a schema, click Edit< next to the resource in the table on the Resources tab. </p>

また、ファイルおよびバックエンドサービスをREST API として公開するために自身でスキーマを書くことができます。例えば、XML をウェブサービスとして公開することができます。

Schema Definitions

API のリソースは、テキストベースのスキーマを書くことで定義されます。Schemas are written in ArcScript, a simple configuration language that allows you to define the columns of the resource.さらに、データベース、ファイル、およびバックエンドサービスを読み書きすることを実現するビルトインオペレーションがあります。

In addition to these data processing primitives, ArcScript is a full-featured language with constructs for conditionals, looping, etc. However, as shown by the example schema, for most resource definitions you do not need to use these features.

The following sections describe a fully functional schema that enables bidirectional access to tables in an SQLite database; you can use the wizard on the Settings > Resources tab to generate similar schemas for your database tables and stored procedures. You can also edit schemas on this tab by clicking ** next to the schema.

このセクションでは、自分でスキーマを書くことで、他のデータソースに読み書きを行うために必要なコンポーネントの詳細な説明をします。Schemas for Resources are written in .rsd files; schemas for Actions are written in .rsb files.ウィザードは、これらのファイルをアプリケーションルートのapi サブフォルダに配置します。You must place your custom schemas in this folder.

このセクションでは、自分でスキーマを書くことで、他のデータソースに読み書きを行うために必要なコンポーネントの詳細な説明をします。 のためのスキーマは、.rsd ファイルで書かれており、 のためのスキーマは.rsb ファイルに書かれています。ウィザードは、これらのファイルをアプリケーションルートのapi サブフォルダに配置します。作成するカスタムスキーマも同じフォルダに格納します。

Mark Up Resource Columns

データベースに接続するときに、リソースのカラムは次の基本属性を持ちます。

  • カラム名
  • データ型
  • カラムが主キーかどうか。

Inside the arc:info block of the schema, you can mark up the columns of the resource with these attributes and others.

<arc:info title="NorthwindOData" desc="Access the Cars database through REST APIs." connection="SQLiteCars">
  <attr name="ID"           key="true" xs:type="int"      />
  <attr name="Make"                    xs:type="string"   />
  <attr name="Model"                   xs:type="string"   />
  <attr name="Cost"                    xs:type="double"   />
  <attr name="CreatedDate"             xs:type="datetime" />
  <attr name="InStock"                 xs:type="boolean"  />
</arc:info> 

Getting Data

When an HTTP GET request is received, the application executes the GET method of the schema. In this method, you can call the application’s built-in operations to process data retrieval requests. The following is an example search request using an HTTP GET:

GET api.rsc/Cars?$filter=Make eq 'Honda'

The preceding request maps to the following SQL query:

SELECT \* FROM Cars WHERE Make = 'Honda'

In the corresponding GET method, the results from the database query are pushed to the application’s HTTP response with the arc:push keyword.データベースに対する検索、ソート、サマリー、および他のデータ取得クエリ実行には、apiSelect オペレーションを使うことができます。

<arc:script method="GET" >
  <arc:push op="apiSelect"/>
</arc:script> 

Posting Data

When a POST request is received, the application executes the POST method of the schema, where you can call data manipulation operations, such as insert.

例として、次のHTTP POST リクエストを考えましょう:

POST api.rsc/Cars
{
  "Model": "Civic",
  "Make": "Honda"
}

The preceding request maps to the following SQL query:

INSERT INTO (Model, Make) VALUES ('Civic', 'Honda')

In the corresponding POST method, you can use the apiInsert operation to execute inserts to databases.

<arc:script method="POST">
  <arc:push op="apiInsert"/>
</arc:script>

いくつかのデータベースではINSERT 構文からデータを返します。例えば、新しいレコードからの発行されたId です。If you want to access values returned from an insert, use the arc:push keyword, as with GET.

Putting Data

When a PUT request is received, the application executes the PUT method of the schema, where you can call data manipulation operations, such as update.

例として、次のPUT リクエストを考えましょう:

PUT http://MyServer:MyPort/connector/MyAPIPortName/api.rsc/Cars('1000') 
{ 
  "Model": "Civic"
} 

次のリクエストは、下のSQL クエリに対応します:

UPDATE Cars SET Model = 'Civic' WHERE Id = '1000'

In the corresponding PUT method, the required input, the primary key, is validated before the operation is called. You can check that an input was provided and alert the user otherwise with the arc:validate keyword.スクリプトに複数のHTTP メソッドを扱わせることを指定することもできます。

Additionally, note that since updates do not typically return data, the arc:call keyword is used to invoke the operation instead. You can call the apiUpdate operation to execute updates to databases.

<arc:script method="PUT,MERGE,PATCH">
  <arc:validate attr="Id" desc="An Id is required to update." />
  <arc:call op="apiUpdate"/>
</arc:script> 

Deleting Data

When a DELETE request is received, the application executes the DELETE method of the schema, where you can call delete operations.例として、次のHTTP DELETE リクエストを考えましょう:

DELETE api.rsc/Cars('1000')

The preceding request corresponds to the following SQL query:

DELETE FROM Cars WHERE Id = '1000'

In the DELETE method, you can call the apiDelete operation to execute deletes to databases.

<arc:script method="DELETE">
  <arc:validate attr="Id" desc="An Id is required to delete." />
  <arc:call op="apiDelete"/>
</arc:script>

Schema Example

次のスキーマは、SQLite データベースのCars テーブルにアクセスし、データの読み書きを実行することができます。これには、HTTP を通じでデータベースにアクセスするために必要なすべてのコンポーネントが含まれています。

<arc:script xmlns:arc="http://www.arcesb.com/ns/ArcScript/2">

  <!-- Define columns and the database connection in the arc:info block -->
  <arc:info title="case" description="Create, Update, Query, and Delete Cars." connection="SQLiteCars"> 
    <attr name="Id"             key="true" xs:type="string"   />
    <attr name="Year"                      xs:type="int"      />
    <attr name="Make"                      xs:type="string"   />
    <attr name="Model"                     xs:type="string"   />
    <attr name="DatePurchased"             xs:type="datetime" />
  </arc:info>

  <!-- The GET method is executed when an HTTP GET is received. You can configure data retrieval operations here. The results of processing are pushed to the schema's output. -->
  <arc:script method="GET">
    <arc:push op="apiSelect"/>
  </arc:script>

  <!-- The POST method is executed when an HTTP POST is received. You can configure insert operations here. Use arc:push to return the Id of the new record. -->
  <arc:script method="POST">
  <arc:validate attr="Make" desc="Make and Model are required to insert a Car."/>
  <arc:validate attr="Model" desc="Make and Model are required to insert a Car."/>
    <arc:push op="apiInsert"/>
  </arc:script>

  <!-- The PUT method is executed when an HTTP PUT is received. You can configure update operations here. Within the script block, the primary key is used to update the record.  Updates typically do not return data, so arc:call is used to invoke the operation. -->
  <arc:script method="PUT,MERGE,PATCH">
    <arc:validate attr="Id" desc="Id is required to update."/>
    <arc:call op="apiUpdate"/>
  </arc:script>

  <!-- The DELETE method is executed when an HTTP DELETE is received. You can configure delete operations here. Within the script block, the primary key is used to delete the record. -->
  <arc:script method="DELETE">
    <arc:validate attr="Id" desc="Id is required to delete."/>
    <arc:call op="apiDelete"/>
  </arc:script>

</arc:script>

Keyword Reference

See the ArcScript Reference for more information on the following keywords used in this section:

Typical Customizations

データソースのリソースは、シンプルかつ拡張が容易なテキストベースのスキーマで定義されています。このセクションでは、頻繁に使われる変更について説明します。To edit a schema, click Settings > Resources and click Edit next to the resource you want to modify.

Remove a Column

Deleting an attr element from arc:info removes the column from the resource. This means that the API does not list the column; also, your cache does not contain the column.カラムの削除では、そのカラムのXML エレメント全体を削除する必要があります。

Change a Resource Column’s Data Type

To change a resource column’s data type, change the xs:type attribute to one of the following supported data types:

  • string
  • datetime
  • boolean
  • int
  • long
  • double

Rename a Resource Column

リソースのカラム名を変更するには、リソースのエレメントを見つけ、alias という名前のアトリビュートを追加し、その内容をカラムの新しい名前にします。name 属性を変更することはできないことに注意してください。This value must remain consistent for the application to maintain the mapping to the correct column in the underlying data source.

The example below renames the Type column to APIType:

<arc:info>
  <attr name="Type" alias="APIsType" xs:type="string" columnsize="40" readonly="True" key="False" />
  ...
</arc:info> 

Rename a Resource

リソース名を変更するには、アプリケーションのルートのapi サブフォルダ内にあるスキーマの.rsd ファイルの名前を変更します。Note that the title attribute in arc:info must remain the same as the name of the table in the underlying data source.

Change the Data Source Connection

You can use the connection attribute in arc:info to change the connection for any given resource.これにより、Sandbox から運用インスタンスへのスイッチが簡単に行えます。

Any changes you make to the connection in the administration console are picked up by all resources that reference the same connection in arc:info, as shown below.

<arc:info title="case" description="Create, Update, Query, and Delete the SQLite Cars database." connection="SQLiteCars">
  ... 
</arc:info>