21 カスタムAPIの設計
Oracle Mobile Cloud Service(MCS)では、モバイル・アプリで使用できるカスタムREST APIを作成できます。 モバイル・アプリケーション開発者の場合は、APIデザイナを使用して、定義したエンドポイントをスケッチしてテストし、サービス開発者にAPIの詳細を記入させる(リソース・タイプまたは特性の追加、スキーマの提供、およびアクセスの設定APIとそのエンドポイントに渡します)、JavaScriptで実装します。 サービス開発者は、APIデザイナを使用してモック・データでテストできる完全なAPIを明示的に構成します。 また、コードを記述することなく、RESTまたはFusion ApplicationsコネクタからカスタムAPIを生成することもできます。
既知のサービスのコア・セットを提供するMCSプラットフォームAPIとは異なり、カスタムAPIを使用すると、Node.jsを使用して、モバイル・アプリが必要とするサービスをコーディングし、RESTインタフェースを介して公開することができます。 複雑なデータをモバイル・フレンドリなペイロードに変換するバックエンド・サービスへのMCSコネクタを使用してデータを中継することができます。 カスタムAPIを使用して再利用可能なサービスのカタログを構築することで、モバイル・アプリケーションの実装詳細を定期的に再作成および保守するのに要する時間を大幅に節約できます。
サンプル・データを提供し、MCSにエンドポイントのセットを定義させることで、APIを素早く作成したい場合は、Express API Designerを使用してください。
API設計プロセス
API Designerは、カスタムAPIの作成プロセスをガイドします。
いくつかのステップを行うだけで、APIのドラフト・バージョンを迅速に作成できます。
-
基本情報(APIの名前、メッセージ・メディア・タイプ、簡単な説明)を追加します。
-
リソースおよび少なくとも1つのメソッドを設定して、エンドポイントを定義します。
-
アクセス・セキュリティを設定します。
-
少なくとも1つのリソースを定義したら、エンドポイントをテストします。
APIの構成が完全に終了していない場合でも、モック・データを作成してエンドポイントを迅速にテストおよび検証できます。 メッセージ本文を定義する際、プレースホルダの値を指定して、正しいデータが送信または返信されることを検証できます。 モック・データを使用したAPIエンドポイントのテストを参照してください。
カスタムAPIの完了
APIを正常に完了するには、API Designerを使用して、堅牢なAPIに不可欠なコンポーネントを追加します。
-
APIメタデータ(API表示名、API名、簡単な説明など、APIの基本属性)を指定するか、APIの構成を含むRAMLドキュメントがすでに存在する場合はそれをAPI Designerにアップロードできます。 すべての情報(メタデータ、リソース、メソッドおよびメッセージ本文のスキーマ)がRAMLドキュメントから抽出されてAPI Designerにロードされるため、エンドポイントのテストやAPI構成の編集にすぐにとりかかることができます。 有効なRAMLファイルを指定するには、「RAML」を参照してください。
-
1つ以上のルート・リソースおよびネストされたリソースを追加します。
-
リソースに対して実行するメソッドを追加します。
-
データの本文を説明するスキーマを作成します。
-
設計時にサンプル・データでエンドポイントをテストし、必要に応じて変更を加えます。
-
APIへの匿名アクセスを許可、またはそれにアクセス可能なロールを指定します。
-
カスタムAPIのドキュメントの追加
後から追加でAPIを作成するときに、たとえば同じパラメータを使用して、同じメソッドを何度も繰返し定義していることに気付くことがあります。このような場合、リソースのタイプと特質を作成することで、重複を削減できます。 APIが依然としてドラフト状態の場合は、構成に戻り、定義したリソース・タイプと特性を追加できます。
API Designer
APIデザイナは、APIに名前を付けたり、エンドポイントを定義したり、セキュリティを構成したり、APIドキュメントを追加したり、スキーマを追加したり、リソース・タイプや特性を定義したり、APIをテストするために使用するタスク固有のタブを使用してカスタムAPIを構成するのに役立ちます。
既存のAPIをダブルクリックすると、自動的にAPIデザイナで開きます。 ドラフト状態のAPIのみ編集可能です。 公開済のAPIを開いた場合、読取り専用情報として表示されます。 公開されたAPIを変更するには、新しいバージョンを作成する必要があります(「新しいバージョンのAPIを作成」を参照)。
APIを構成する際、設計ビューとソース・ビューを切り替えることができます。 設計ビュー(デフォルト・ビュー)では、各フィールドに値を入力します。 ソース・ビューでは、ソース・コード・エディタでAPIのプロパティを手動で定義します。 設計ビューとソース・ビューを切り替えるには、「Enter RAML Source Editor Mode」
をクリックします。
注意:
モバイル・バックエンドから「APIs」ナビゲーション・リンクをクリックしてAPI Designerに移動した場合、RAMLドキュメントをアップロードする機能は使用できません。MCS APIは、RESTful APIモデリング言語(RAML)標準に基づいています。 APIを構成し始めると、MCSは構成のRAML文書を生成します。 詳細については、RAMLを参照してください。
MCSの外部でRAML文書を処理する場合は、ページの上部にある「RAML文書をエクスポート」 
をクリックして、そのファイルをエクスポートすることができます。
コネクタのカスタムAPIの生成
Oracle Mobile Cloud Service (MCS)は外部サービスに接続するコネクタからカスタム・コードを生成できます。 サービス開発者は、有効なディスクリプタで作成されたFusion ApplicationsコネクタまたはRESTコネクタを選択し、カスタムAPIを生成し、生成されたAPIを使用して、カスタムAPIの実装からこれらのサービスを簡単に呼び出すことができます、またはモバイル・アプリから直接送信することができます。
コネクタは、モバイル・バックエンドがエンタープライズ・システムやサードパーティのAPIなどの外部サービスと通信できるようにする手段であり、モバイル・アプリはそのサービスの機能とやりとりすることができます。 コネクタAPIは、特定の外部サービスと通信してデータを送受信するための構成です。
サービス開発者は、コネクタAPIのメソッドを公開し、コードを記述することなくデフォルトの実装を提供するカスタムAPIを生成できます。
カスタムAPIは、コネクタAPI内の各リソースのエンドポイントを使用して生成され、引き続き、APIの詳細(ロールなど)を指定できるようにAPIデザイナで開きます。 デフォルトの実装では、生成されたカスタムAPIからターゲット・コネクタAPIに送られるすべてのリクエストが生成され、生成されたAPIに割り当てられます。 コネクタのセキュリティに必要なロールをAPIに割り当てるとすぐに、その実装を使用してAPIをテストできます。 実装をダウンロードして変更し、アップロードすることができます。
生成されたカスタムAPIの作成
コネクタ用のカスタムAPIを作成できることは、コネクタをテストするために使用するプロトタイプを作成する方がはるかに簡単であることを意味します。 変更したいものが見つかると、すぐにコネクタを変更して、新しいカスタムAPIと実装を生成することができます。 満足したら、カスタムAPIと実装の最終バージョンを生成できます。
-
まず、ディスクリプタを使用して定義されたRESTコネクタまたはFusion Applicationsコネクタを開発します。
-
コネクタからカスタムAPIを生成します。 1つ以上のロールを定義したり、APIに必要な認証を指定することができるAPIデザイナで開きます。
-
モバイル・デバイスから生成されたAPIをすぐに呼び出すことができます。 デフォルトの実装では、生成されたAPIからターゲット・コネクタAPIへのすべてのリクエストが渡されます。
-
実装をダウンロードして修正して、返されるデータを整形したいと思うでしょう。
-
コネクタを再訪して、コネクタ・リソースまたは記述子を変更することができます。 新しいカスタムAPIと実装を生成する必要があります。 生成されたカスタムAPIを変更すると、これらの変更はコネクタに反映されません。 コネクタで適切な変更を行い、カスタムAPIと実装を再度生成する必要があります。
生成されたカスタムAPIのコネクタの制限
ディスクリプタを使用して定義されたRESTまたはFusion Applicationsコネクタ用のカスタムAPIのみを生成できます。 別のタイプのコネクタ、またはRESTまたはFusionアプリケーション・コネクタに記述子がない場合は、カスタムAPIを生成できません。
マルチパート・フォーム・データを送信するか、httpオプション・オブジェクトを使用する場合は、実装のcallConnectorメソッドを独自のコードに置き換える必要があります。 「カスタム・コードからConnector APIを呼び出す」を参照してください。
コネクタからカスタムAPIを生成する方法
-
記述子URLを使用するRESTコネクタ
-
Fusionアプリケーション・コネクタ
注意:
コネクタに定義された記述子があること、およびコードを生成するリソースおよびメソッドを選択したことを確認してください。 コネクタは可能な限り完全でなければなりません-
カスタムAPIを生成する環境にいることを確認してください。
-
をクリックして、サイド・メニューから「Applications」→「APIs」を選択します。
「コネクタ」ページが表示されます。 カスタム・コードを生成するコネクタAPIを選択します。 関心のあるコネクタAPIだけを表示するには、リストをフィルタに掛けるか、「ソート」をクリックしてリストの順序を変更します。
-
「詳細」をクリックし、ドロップダウン・リストから「カスタムAPIを生成する」を選択します。
「カスタムAPIの生成」ダイアログが表示されます。 -
生成されたカスタムAPIには、次の情報を入力します。
-
タイトル: わかりやすい名前(APIを明確に識別する読みやすい名前のAPIを使用すると、カスタムAPIのリスト内での検索がより簡単になります)を入力します。
たとえば、
myCustomAPIです。注意:
カスタムAPIに付けた名前(API名フィールドに入力する値)は、カスタムAPI間で一意である必要があります。 -
バージョン: バージョン番号を入力します。
既に存在するバージョン番号を入力すると、その番号がすでに使用中であることを知らせるメッセージが表示されます。
-
名: 入力したタイトルは自動的にここに名前として入力されます。 必要に応じて変更することができます。 この名前は、カスタムAPIの一意の名前として使用されます。
デフォルトでは、この名前はカスタムAPIのリソース名として相対ベースURIに追加されます。 名前フィールドの下にベースURIが表示されます。
注意:
カスタムAPI名は、英数字のみで構成する必要があります。 特殊文字、ワイルドカード、スラッシュ /,、中カッコ {}は使用できません。ここでAPIの名前を編集すると、ベースURIが自動的に更新されます。
このカスタム・コネクタAPIの新しいバージョン以外では、他のカスタム・コネクタAPIには同じリソース名を使用できません。
-
説明: デフォルトの説明を受け入れるか、このAPIの目的を含む簡単な説明を入力することができます。
必要なフィールドをすべて入力したら、「生成」をクリックします。
APIのドラフトは、APIデザイナの全般ページ(「APIデザイナ」を参照)に生成されて表示され、そこで編集を続行できます。
-
新しいカスタム・コネクタAPIは、「アプリケーション」>「API」の下にリストされています。
カスタムAPIの完成
生成されたAPIは、APIデザイナで開きます。
-
エンドポイントは、コネクタで選択されたすべてのリソースと、APIをテストするために使用できるインプリメンテーションのために存在します。
-
デフォルトでは、ログインは必須でセキュリティはエンタープライズ・レベルなので、APIにアクセスできるロールを追加する必要があります。 「カスタムAPIのセキュリティ」を参照してください
適切なロールを割り当てるとすぐに、カスタムAPIをテストできます。
実装の使用
デフォルトで生成された実装はすべてのリクエストを通過しました。 実装を編集して返されるデータを整形することができます。データが多い場合に便利です。
-
実装をダウンロードできる環境にいることを確認してください。
-
をクリックして、サイド・メニューから「Applications」→「APIs」を選択します。
「API」ページが表示されます。 生成したカスタムAPIを選択します。 リストをフィルタリングして、関心のあるカスタムAPIのみを表示するか、「ソート」をクリックしてリストを並べ替えることができます。
-
「実装」ナビゲーション・リンクをクリックし、カスタムAPIと同じ名前を持つ実装を選択して、「ダウンロード」をクリックします。
-
ダウンロードは、デフォルト名が
<custom-api><version>.zipのzipファイルです。 適切なロケーションに展開します。 実装ファイルは次のとおりです。-
callConnector.jsは、クライアントのリクエストをコネクタに渡し、コネクタのレスポンスを返します。 -
<custom_api>.jsは、カスタムAPI実装のスキャフォールドの本文を提供します。 この中の行のコメントを解除して、コネクタから戻されたデータを整形することができます。 -
<custom_api>.raml、カスタムAPIのRAML定義 -
package.json、パッケージ記述子ファイル。 -
ReadMe.mdには、実装ファイルの説明があります。 -
samples.txt、コード・サンプル。 -
swagger.json、カスタムAPIのSwagger定義。 -
toolsConfig.json、コマンドライン開発ツールで使用されます。
-
-
適切なエディタで、
<custom_api>.jsを開きます。これは、編集する必要のある生成された実装の唯一のファイルです。コネクタからレスポンスを形成するには、関連する行のコメントを外し、必要に応じて
typeとlimitを変更します。 下記の<custom_api>.jsのサンプルのservice.useの例を参照してください。service.use(bodyParser.raw({type: 'application/octet-stream', limit: '100mb'}));and
service.use(bodyParser.text({type: 'text/*', limit: '1mb'}));これは、
<custom_api>.jsで生成された実装ファイルの最初の数行です。// no need to add body-parser as a dependency in package.json - it's provided by custom code container var bodyParser = require('body-parser'); // passes client's request to the connector, sends back connector's response var callConnector = require('./callConnector.js'); /** * Mobile Cloud custom code service entry point. * @param {external:ExpressApplicationObject} * service * @see {@link http://expressjs.com/en/4x/api.html} */ module.exports = function(service) { // uncomment if using customizer to customize binary request with content-type 'application/octet-stream' - it will be parsed into a Buffer and assigned to req.body. Otherwise these requests streamed through (recommended approach if no customization is required). //service.use(bodyParser.raw({type: 'application/octet-stream', limit: '100mb'})); // uncomment if using customizer to customize text request with text content-type - it will be parsed into a string and assigned to req.body. Otherwise these requests streamed through (recommended approach if no customization is required). //service.use(bodyParser.text({type: 'text/*', limit: '1mb'})); // In the product UI, in Diagnostics -> Logs tab, ServerSetting button allows to set backend log level: set your mbe log level to FINE (FINER, FINEST) to see the generated custom code sdk calls. service.post('/mobile/custom/sample_api/emps', function(req,res) { // uncomment customizer to customize request and/or response callConnector(req, res/*,customizer*/); }); service.get('/mobile/custom/sample_api/emps', function(req,res) { // uncomment customizer to customize request and/or response callConnector(req, res/*,customizer*/); }); ...
生成された同じ実装ファイルにサンプル・カスタマイザがあります。 それを編集し、最後のパラメータとしてcallConnectorに渡して、コネクタに送信されたリクエストやコネクタのレスポンスを上書きすることができます。 できることの例については、コード内のコメントを参照してください。
// Edit this sample customizer and pass it as a last parameter to callConnector to override request sent to connector and/or connector's response.
// Without customizer callConnector streams request to connector, then connector's response is streamed back to client - recommended approach in case no customization is required.
var customizer = {
// allows to customize request sent to connector. If omitted then the request streamed to the connector - recommended approach in case no request customization is required.
request: {
// used - with post and put only - to customize request body
// If not specified then request body is streamed directly to the connector - no need to define this function unless you need to override the payload.
body: function(req) {
console.log('customizer.request.body: req.body = ', req.body);
var body = req.body;
// OVERRIDE request body here - substitute this sample code:
if (typeof body == 'string'){
// to enable string parsing uncomment service.use(bodyParser.text... - otherwise req.body would never be a string
body += ' customized request';
} else if (typeof body == 'object'){
if (Buffer.isBuffer(body)){
// to enable binary parsing uncomment service.use(bodyParser.raw... - otherwise req.body would never be a Buffer
body = Buffer.concat([Buffer.alloc(8, '00000000'), body]);
} else {
// json parsing is enabled by default
body['customized-request'] = true;
}
}
console.log('customizer.request.body ->', body);
return body;
}/*,
// advanced: uncomment to add options to connector request, see https://github.com/request/request#requestoptions-callback
options: function(req) {
var options = {headers: {myHeader: 'myHeaderValue'}};
console.log('customizer.request.options ->', options);
return options;
}*/
},カスタムAPIのスペック・アウト
モバイル開発者は、バックエンド用のAPIをすぐに特定し、後で構成するか、サービス開発者などの誰かに渡して完了させることができます。 わずかなステップで機能するAPIを構築できます: APIに名前を付け、エンドポイントを定義し、エンドポイントをテストします。 これらの次のステップでは、単純化されたFixItFastの例を使用します。 メソッドのパラメータ、スキーマ、リソースのタイプおよび特質を追加する方法は示されていません。
をクリックして、サイド・メニューから「Applications」→「Mobile Backends」を選択します。- 「New API」→「API」を選択します。
- ナビゲーション・バーで「Endpoints」をクリックして、APIのエンドポイントを定義します。
- をクリックして、リソース名とリソースの表示名(リソース名フィールドの横のフィールド)を入力します。 たとえば、リソース名として
contactsを、表示名としてCustomer contactsを使用できます。 リソースは、「API Test」ページの左側に表示名別にリストされます。 リソースの内容を理解できるように、リソースの簡単な説明を入力します。ヒント: この画像では、「Methods」リンクの下に"P"が示されています。 エンドポイントに対してメソッドが定義されている場合は、「Methods」リンクの下にメソッドのアイコンが表示されます。 このアイコンは、リソースに対してどのメソッドが定義されているかを素早く確認するためのショートカットです。アイコンをクリックすると、メソッド定義に直接移動できます。
新たな最上位リソースを追加する場合は、再び「New Resource」をクリックして名前と説明を入力します。
- をクリックして、リソース名とリソースの表示名(リソース名フィールドの横のフィールド)を入力します。 たとえば、リソース名として
- リソースの表示名の横にある「Methods」をクリックして、リソースのメソッドを定義します。それぞれのメソッドについて、リクエストとレスポンスを定義する必要があります。 必要に応じてパラメータを追加し、リクエストおよびレスポンス・メッセージ本文の情報をフィルタリングできます。
- 「ログインが必要です」を
OFFに切り替えると、認証のためにモバイル・ユーザーの資格証明またはトークンにアクセスする必要はなく、保存をクリックします。APIアクセスの保護の詳細は、カスタムAPIのセキュリティを参照してください。 これで、エンドポイントをテストする準備が整いました。
- 「Test」をクリックしてAPI testingページに移動します。APIに定義されるエンドポイントは、ページの左側にリストされます。 エンドポイントをクリックしてロードします。 リソースごとに各メソッドのリクエストおよびレスポンス構成を確認できます。
各メソッドの定義を確認することができます。パラメータ名や例を変更する場合は、フィールドの右側にあるボックスに変更を入力します。 メッセージ本文で「使用例」をクリックすると、現在の本文がテキスト・エディタにコピーされ、変更を加えることができます。
- 「Authentication」セクションで、このAPIが関連付けられているモバイル・バックエンドを選択し、そのモバイル・バックエンドのバージョン番号を選択します。
Login Requiredを
OFFに設定するため、認証メソッドを指定する必要もなく、資格証明を指定する必要もありません。複数のエンドポイントを定義した場合は、メソッドごとに「Authentication」フィールドを入力しなくてもよいように、デフォルトのテスト資格証明を設定します。 ページ上部で「Default API Designer Test Credentials」をクリックして、関連付けられているモバイル・バックエンドとそのバージョン番号を選択します。 「Save」(
)をクリックすると、各メソッドの「Authentication」フィールドに値が適用されます。
完全なカスタムAPIの作成
これまで、API Designerを使用してAPIをスペック・アウトする方法について説明してきました。 APIに名前を付けて、少なくとも1つのリソースおよびメソッドを追加し、エンドポイントをテストしました。 この時点では、APIのドラフト・バージョンは作成されましたが、すべて完了したわけではありません。 このセクションでは、堅牢なAPIを作成するために、より詳細な作業を行います(メソッドのリクエストおよびレスポンスの定義、スキーマの追加、セキュアなアクセスの設定など)。 最初から行う場合または基本事項の設定について詳しく知りたい場合のために、カスタムAPIを作成する完全なステップを示します。
をクリックして、サイド・メニューから「Applications」→「APIs」を選択します。 APIがすでに作成されている場合(ドラフト状態であれ公開済状態であれ)、APIのリストが表示されます。 カスタムAPIが存在しない場合、ページに「New AP」ボタンが表示されています。 すでにスペック・アウトしたAPIをクリックするか、「New AP」をクリックして作業を開始します。
APIの設定
それでは、FixItFastの例を使用してカスタムAPIを作成します。 この例では、FixItFast機器修理会社で仕事をしています。 修理コールおよびレスポンスを追跡する方法を探しています。 修理ジョブに割り当てられている技術者を把握することも有用です。 問題を報告する電話をかけてきた顧客、顧客の場所、ジョブに割り当てられている技術者に基づいてカスタマ・サービス・コールをリストするAPIを作成したいと考えています。 次のプロパティを持つ次のAPIを作成します。
-
FIFIncidentReportsというAPI -
ベースURI :
https://fif.mcs.cloud.oracle.com/mobile/custom/fif-incidentreport/ -
application/jsonメディア・タイプ -
API表示名に関連付けられているアイコン(選択したPNGファイル)
「Create」をクリックすると、ドラフト状態のAPIが作成され、カスタムAPIのリストに追加されます。
まずGeneralページに移動して、APIの基本特性を設定します。
- をクリックして、サイド・メニューから「Applications」→「APIs」を選択します。
エンドポイントの定義
リソースを作成してAPIのエンドポイントを定義します。 リソースはAPIの最重要ポイントです。 リソースにはタイプがあり、なんらかのデータが関連付けられており、他のリソースとのリレーションシップがあり、リソースに対して実行される1つ以上のメソッドが含まれます。 イメージ、テキスト・ファイル、他のリソースのコレクション、論理トランザクション、プロシージャなど、ほぼ何でもリソースになります。APIリソースを参照してください。
- 「New Resource」をクリックして、いくつかの基本情報を追加します。「New Resource」をクリックするたびに、最上位(ルート)リソースが作成されます。 子(ネストされた)リソースを追加する場合は、最上位リソースの横にある「Add」(+)をクリックします。 リソースを削除するには、Xをクリックします。
注意:
「Methods」リンクの下のアイコンがわかりますか。 リソースに対してメソッドを定義するたびに、そのメソッドのアイコンが「Methods」リンクの下に表示されます。 それらをショートカットとして使用して、リソースに対してどのメソッドが定義されているかを表示します。 アイコンをクリックすると、「Methods」ページの定義に直接移動できます。
リソースのメソッドを作成すると、そのメソッドの記号が「Methods」リンクの下に表示されます。 リソース定義を調べる必要がある場合、どのメソッドがリソースに定義されているかをすぐに確認できます。 アイコンをクリックすると、そのメソッド定義に直接移動します。
「Compact Mode」(「New Resource」の右にある)に切り替えることで、すっきりさせてリソースをより迅速に見つけることができます。 コンパクト表示にすると、リソースの説明、リソース・タイプおよびパスが非表示になります。
リソースへのメソッドの追加
メソッドは、リソースに対して実行できるアクションです。 「Methods」ページには、一度に1つのメソッドのみ表示されます。 2つ以上のメソッドを定義した場合は、ページの上部でメソッドのアイコンをクリックして詳細を表示できます。
リソースのメソッドを定義したら、それらのメソッドのリクエストとレスポンスを定義できます。 メソッドのリクエストの定義およびメソッドのレスポンスの定義を参照してください。
メソッドのリクエストの定義
メソッドを選択したので、接続するサービスに対するリクエストを定義します。 たとえば、POSTメソッドを選択した場合、作成するものを定義することができます。 それには、パラメータおよびサービスに送信するデータの説明を含むリクエスト本文を追加します。
- 「Request」をクリックしてリクエストを定義します。
- 「Add Parameter」をクリックしてパラメータ・タイプ(問合せまたはヘッダー)を選択します。 メソッドにとってそのパラメータが必須の場合は、「Required」を選択します。
- 選択したメソッドによっては、「Add Media Type」をクリックしてメソッド本文を定義します。 本文には、サーバーに送信するデータが含まれます。 たとえば、
POSTメソッドを定義する場合は、新しい顧客リストやサービス・リクエストなど、作成するアイテムを定義する必要があります。GETメソッドを定義する場合は、メソッド本文を送信する必要がないため、メディアのタイプを指定する必要はありません。 - 「Add Media Type」をクリックして、メディア・タイプを追加します。 メソッドが必要ないと判断した場合は、バナーでXをクリックして削除します。
メソッドのレスポンスの定義
リクエストによって、レスポンスが必要な場合と必要でない場合があります。 レスポンスは、サービスから結果を返すプロセスを示します。 リクエストしたデータが返されたことを確認するレスポンス、またはリクエストが受信されたかどうかのみを確認するレスポンスを定義できます。 レスポンスの定義は、リクエストの定義と似ています。 主な違いは、接続結果を知らせるステータス・コードを選択する必要がある点です。
incidentsリソースのPOSTメソッドに対するレスポンスが、新しいリソースが正常に作成されたことを示すステータス・コード201で作成されたことを示しています。 この例では、application/json、Locationヘッダー、およびモック・データを含むメッセージ本文のリターン・レスポンス・フォーマットも示しています: responses:
201:
description: |
The request has been fulfilled and resulted in a new resource
being created. The newly created resource can be referenced
by the URI(s)returned in the entity of the response, with the
most specific URI for the resource given by a Location header
field.
headers:
Location:
displayName: Location
description: |
Identifies the location of the newly created resource.
type: string
example: |
/20934
required: true
body:
application/json:
example: |
{
"id": 20934,
"title": "Lynn's Leaking Water Heater",
"contact": {
"name": "Lynn Adams",
"street": "45 O'Connor Street",
"city": "Ottawa",
"postalcode": "a1a1a1",
"username": "johnbeta"
},
"status": "New",
"driveTime": 30,
"priority": "high",
"notes": "My notes",
"createdon": "2014-01-20 23:15:03 EDT",
"imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d74331d77/objects/6cdaa3a8-097e-49f7--9bd2-88966c45668f?user=lynn1014"
}レスポンスを定義したら、エンドポイントをテストするか(「モック・データを使用したAPIエンドポイントのテスト」を参照)、ナビゲーション・バージョンで「<Endpoints」をクリックしてリソースのメイン・ページに戻るかを決定できます。 そこからAPI Designerの別のページに進んで、ルート、リソース・タイプまたは特質を作成したり、APIドキュメントを追加できます。
メソッドが必要ないと判断した場合は、バナーでXをクリックして削除します。
モック・データを使用したAPIエンドポイントのテスト
API構成の設計フェーズでは、リクエストおよびレスポンス・メッセージ本文にモック・データを入力できます。 これにより、リアルタイム・データを使用したりリアルタイム・サービスと相互作用することなく、各呼出しのコンテキストを調べることができます。 たとえば、コードが無効なIDを正しく処理するかどうかテストするために、無効なIDを含むモック・データを使用した例をリクエスト本文に追加できます。 テストが終了したら、例を別のコードに置き換えて、メソッドの他の側面をテストできます。
contactリソースのPOST操作のレスポンス本文に対して作成できる模擬データの例を示します: {
"id": 20934,
"title": "Lynn's Leaking Water Heater",
"contact": {
"name": "Lynn Adams",
"street": "45 O'Connor Street",
"city": "Ottawa",
"postalcode": "ala1a1"
"username":"johneta"
}
"status": "new",
"driveTime": 30,
"priority": "high",
"createdon": "2015-04-23 18:12:03 EDT"
}カスタムAPIを作成すると、モック実装が自動的に作成されます。 モック実装により、カスタム・コードを実装する前に、モバイル・アプリケーションからAPIを呼び出すことができます。 これにより、モバイル・アプリケーションとカスタム・コードを同時に開発およびテストできます。 構成に満足したら、実際の実装を追加できます。
最初の実装を作成するまでは、デフォルト実装がモック実装です。 実際の実装を作成した後は、それがAPIのデフォルトの実装になります。
「Implementations」ナビゲーション・リンクをクリックして、実装をアップロードするか、既存の実装があるかどうかを確認します。 デフォルト実装は、Implementationsページで変更できます。 実装をアップロードすると、モック実装を含む既存の実装のリストが表示されます。
模擬実装でAPIをテストする方法の詳細については、「モック・データによるテスト」を参照してください。 API実装の作成については、Implementing Custom APIsを参照してください。
完全に実装されたカスタムAPIのテストの詳細は、Testing Your Custom APIを参照してください。
スキーマの指定
データの構造を示し、JSONで記述されている、JSONスキーマを追加するオプションが用意されています。 スキーマを追加する場合は、Schemaページに移動して「New Schema」をクリックします。 少なくとも1つのスキーマを定義したら、リストから選択できます。
スキーマを定義するには、次を指定します。
-
スキーマ名
-
エディタ・ペインでスキーマ定義(JSON形式)を指定します。エディタに手動で入力するかコピー・アンド・ペーストできます
たとえば、schema#というスキーマは、次のように定義されます:
schemas:
- reports: |
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Incident Reports array",
"items": {
"type": "object",
"properties": {
"id": { "description": "Unique id for the incident report",
"type": "integer" },
"title": { "description": "Title for the incident report",
"type": "string" },
"createdon": { "description": "Date and time of creation",
"type": "string" },
"contact": { "decription": "Contact information of customer filing the report",
"type": "object",
"properties": {
"id" : { "description": "Unique id for the customer",
"type" : "string" },
"name" : { "description": "First and last name of contact",
"type" : "string" },
"street": { "description": "Street address of contact",
"type" : "string"},
"city" : { "description": "City of contact",
"type" : "string"},
"postalcode" : { "description" : "Postalcdoe of contact",
"type": "string" }
}
},
"status" : { "description": "The current status of the incident",
"type" : "string" },
"priority" : { "description": "The current priority of the incident",
"type" : "string" },
"driveTime" : {"description" : "Calculated field based on location",
"type" : "integer"},
"imageLink" : { "description" : "Link to image from Storage",
"type": "string" }
},
}
}「New Schema」をクリックして、さらにスキーマを定義できます。 スキーマを削除するには、Xをクリックします。 JSONスキーマの構造の詳細は、Schemasを参照してください。
注意:
特定のAPIで使用するために、複数のスキーマを定義できます。 スキーマはAPIに固有であり、他のAPIとは共有されません。カスタムAPIのセキュリティ
MCSでは、APIはモバイル・バックエンドとの関連によって保護され、許可されたユーザーとデバイスだけがAPIとそのエンドポイントにアクセスできるようにします。
エンタープライズ・アプリケーションごとに、HTTP Basic認証、OAuthまたはSSO OAuthトークン資格証明を使用して、ユーザー認証およびリソースへのアクセスの認可を制御できます。
-
OAuthでは、モバイル・バックエンドを作成するか、既存のモバイル・バックエンドに登録すると、クライアントIDとクライアント・シークレットで構成された一連のOAuthコンシューマ・キー(クライアント資格証明)が生成されます。 これらのキーの値は、モバイル・バックエンドに固有です(OAuthによる認証については、「直接REST呼び出しでのOAuthによる認証」を参照してください)。 クライアント資格証明を指定して、OAuthサーバーに対して自身を認証し、ヘッダーを介して各APIコールで渡されるアクセス・トークンを受信します。 APIにアクセスできるのは、有効なトークンを持つユーザーのみです。
あるいは、モバイル・バックエンドに対して「SSOの有効化」オプションが選択されている場合は、リモート・アイデンティティ・プロバイダが提供するシングル・サインオンOAuthトークンを提供できます。 モバイル・バックエンドでシングル・サインオンを有効にする方法については、「MCSでの認証」を参照してください。
-
HTTP Basic認証では、モバイル・バックエンド作成されると、モバイル・バックエンドIDと匿名アクセス・キーが生成されます。 ヘッダーを介して各API呼び出しで渡されるこれらのアイテムを提供することによって、MCSに自分自身を認証します。 APIにアクセスするには、この情報を指定する必要があります。 モバイル・バックエンドIDと匿名アクセス・キーは、モバイル・バックエンドのランディング・ページから取得できます。 APIに関連付けられているモバイル・バックエンドを選択して、「Keys」セクションを展開します。 HTTP Basicによる認証の詳細については、「直接REST呼び出しでのHTTP基本認証」を参照してください。
-
ソーシャル・アイデンティティを使用してアプリをソーシャル・アイデンティティ・プロバイダ(Facebookなど)に登録する際は、アクセス・トークンはプロバイダによって生成されます。 ソーシャル・アイデンティティ・プロバイダを指定し、アクセス・トークンを指定することによって、MCSに自分自身を認証します。
アクセス・トークンの取得方法の詳細は、「手動によるFacebookユーザー・アクセス・トークンの取得」を参照してください。
MCSでの認証については、「エンタープライズ・シングル・サインオン(MCS)」を参照してください。
APIへのアクセスの設定
開発者にログインし、APIにアクセスするための資格証明を提供するように要求するオプションがあります。
-
「ログインが必要です」を
OFFに設定すると、匿名ユーザーとしてモバイル・アプリからAPIにアクセスできます。 また、「APIテスト」ページで認証資格証明を使用する必要もありません。この設定は、APIの構成の初期段階にあり、一部のエンドポイントを検証するのみの場合や、リクエストまたは受信されるデータがセキュリティを必要としないサービスからのものである場合に特に便利です。
-
「ログインが必要です」を
ONに設定して、APIへの認証アクセスを要求する:-
MCSのユーザー名とパスワードでログインするモバイル・ユーザー、またはシングル・サインオン認証プロバイダを構成したモバイル・ユーザーのアクセスを構成するには、「エンタープライズ」を選択します。
「ログインが必要です」を
ONに設定して「エンタープライズ」を選択すると、API Accessおよび「エンドポイント・アクセス」フィールドが公開され、APIにアクセスするために少なくとも1つのロールを選択する必要があります。 これにより、選択されたロールを持つモバイル・ユーザーのみがAPIエンドポイントにアクセス可能であることを保証できます。 「Roles」フィールドをクリックして、1つ以上のロールを選択します。オプションで、特定のエンドポイントのロールを選択して、APIへのアクセスをさらに調整できます。 特定のエンドポイントに選択されたロールを持つモバイル・ユーザーのみがそれにアクセスできるようになります。 たとえば、Mobile Developのロールを持つユーザーだけが
DELETEメソッドにアクセスできるようにすることができます。 各エンドポイントのフィールドをクリックして、1つ以上のロールを選択します。 -
認証にソーシャル・メディア・アカウントを使用するモバイル・ユーザーのためのアクセスを設定するには、「Social Identity」を選択します。
この設定を選択すると、API構成が保存され、「Test」ページに移動します。 モバイル・バックエンドおよびそのバージョンの指定に加え、ソーシャル認証プロバイダを選択し、選択したプロバイダによって生成されるアクセス・トークンの入力が求められます。
-
注意:
ums.getUserExtended()メソッドをAPIのカスタム・コードに組み込むことにより、現在のモバイルおよびソーシャル・ユーザーに関する情報を取得できます。 「カスタム・コードからMobile Users APIへのアクセス」を参照してください。
カスタムAPIのテスト
注意:
APIのテストを開始する前に、いくつか注意する点を示します。-
「ログインが必要です」を
ONにしてEnterpriseを選択した場合は、APIへのアクセスを許可するロールが割り当てられている必要があります。 -
「ログインが必要です」を
ONに変更し、エンタープライズまたはソーシャル・アイデンティティを選択した場合は、各メソッドの認証セクションのすべてのフィールドに値を入力してテストする必要があります。 -
「ログインが必要です」が
OFFになっている場合、認証資格証明を指定することはオプションです。 -
テストを行う前に構成を保存します。 まだの場合は、「Test」をクリックしたときに表示される「Save Before Testing」確認ダイアログの「Always save before testing」オプションを選択できます。 こうすることで、API構成に加えた変更はすべて自動的に保存されます。
- 設計フェーズで、エンドポイントが有効かどうかのみを確認する場合、またはセッション中に複数のエンドポイントをテストする場合は、デフォルトのAPIテスト資格証明を設定します。
- 「Save」()をクリックします。
入力するモバイル・ユーザー資格証明が、Mobile Cloud Service内で行われるすべてのテスト・コールのデフォルトの資格証明として使用されます。
いくつかのメソッドのみをテストする必要がある場合は、ステップ1をスキップして各メソッドの「Authentication」セクションのフィールドに値を入力します(ステップ5を参照)。 - 「Save」(
- テストするメソッドをテスト・ページの左側のエンドポイントのリストから選択します。
エンドポイントを選択すると、そのメソッド・バナーが表示され、ベースURIが操作名の下に表示されます。 操作の代替名を指定した場合はその名前が表示され、それ以外の場合はデフォルトの操作名が表示されます。 テスト用に一度に表示されるメソッドは、エンドポイントごとに1つのみです。
シングル・サインオンOAuthトークンの取得方法は、MCSでのEnterprise Single Sign-Onを参照してください。
ソーシャル認証プロバイダからのアクセス・トークンの取得方法は、手動によるFacebookユーザー・アクセストークンの取得を参照してください。
リソース・タイプの作成
インシデント・レポートの例を使用して、複数の部門(請求、サービス技術者、事務)のレポートを取得できます。 部門ごとに、特定のインシデントに関連する従業員のリストを取得でき、各従業員の名前、IDおよび内線番号を取得できます。 必要なすべての人事情報を取得するGETメソッドを定義するリソース・タイプemployee_contactを定義できます。 会社の各ブランチにemployee_contactを定義する代わりに、各インシデント・レポート・リソースにemployee_contactリソース・タイプを適用することができます。
注意:
リソース・タイプは、ネストされたリソースでは使用できません。
特定のAPIで使用するために、複数のリソース・タイプを定義できます。 リソース・タイプはAPIに固有であり、他のAPIとは共有されません。
API Designerでリソース・タイプを追加するのは簡単です。
- 「Types」、「New Resource Type」の順にクリックします。「Types」ページが表示されます。
リソースの特質の作成
特質は、説明、ヘッダー、クエリー文字列パラメータ、レスポンスなどのメソッド・レベルのプロパティを指定する部分的なメソッド定義です。 特質は、バージョン番号やベンダー情報などの説明的な情報を取得するために定義します。 1つ以上の特質を使用するメソッドは、これらの特質のプロパティを継承します。 リソース・タイプと同様に、同じ属性を持つメソッドを複数回定義する場合、特質を定義してメソッドに特定の属性を事前移入します。 リソース特質を使用する必要はありませんが、同じ操作構造を持つ複数のメソッドがある場合、リソース特質は便利です。
注意:
特定のAPIで使用するために、複数のリソース特質を定義できます。 リソース特質はAPIに固有であり、他のAPIとは共有されません。次に、リソース特質を定義する方法を示します。
- API Designerで「Traits」ナビゲーション・リンクをクリックして「New Trait」をクリックします。「Traits」ページが表示されます。
APIドキュメントの提供
優れたAPIであっても、他のユーザーもそのAPIを使用できるようにAPIを説明するドキュメントがなければ役には立ちません。 API Designerでそのドキュメントを記述することはできませんが、API Designerを使用してアップロードすることはできます。これにより、次回ユーザーまたは他のユーザーがAPIカタログからこのAPIを選択したときに、APIの完全な説明(目的、リソースおよびスキーマ、使用するセキュリティ・ポリシー、有用なコード・コメント)が表示されます。
- ソース・エディタでMarkdown構文を使用してAPIドキュメントを手動で記述することも、ドキュメントをエディタにコピー・アンド・ペーストすることもできます。
「Markdown Reference」をクリックして、Markdownの使用方法を確認します。 これにより、読みやすいプレーン・テキストを記述し、構造的に有効なXHTMLに容易に変換してブラウザで表示できます。 Markdownで記述する方法を参照してください。
次に、FIFIncidentReports APIのAPIドキュメントの例を示します。
Markdownで記述する方法
Markdownは、項の見出し、段落、順序付きの項目化されたリスト、ブロック引用、リンクなどの基本的なフォーマット構造を生成するための単純な構文のセットです。
| 構造体 | Markdown | 出力 |
|---|---|---|
|
ヘッダー: ハッシュ・マーク(#)を使用してヘッダーであることを示します |
#第1レベルの見出し ##第2レベルの見出し ###第3レベルの見出し |
第1レベルの見出し 第2レベルの見出し 第3レベルの見出し |
|
段落: 1つ以上の空白行で段落を分割します。 |
これは段落です。 これは2つめの段落です。 |
これは段落です これは2つめの段落です。 |
|
簡単なリスト: +、-または*の後にスペースを入れて、リスト・アイテムであることを示します。 リスト・マーカーは交換可能です。 |
- リスト・アイテム1 + リスト・アイテム2 * リスト・アイテム3 |
- リスト・アイテム1 - リスト・アイテム2 - リスト・アイテム3 |
|
ネストされたリスト: +、-または*の後にスペースを入れてリスト・アイテムであることを示し、4つのスペースを入れてインデント・ネストされたリスト・アイテムであることを示します。 |
-リスト・アイテム1 + リスト・アイテム1a + リスト・アイテム1b -リスト・アイテム2 |
- リスト・アイテム1 - リスト・アイテム1a - リスト・アイテム1b - リスト・アイテム2 |
|
順序付きリスト: 各アイテムの前には連続する数値が付けられ、その後にスペースが挿入されます。 |
1. リスト・アイテム1 2. リスト・アイテム2 * リスト・アイテム2a * リスト・アイテム2b 3. リスト・アイテム3 |
1. リスト・アイテム1 2. リスト・アイテム2 2a. リスト・アイテム2a 2b. リスト・アイテム2b 3. リスト・アイテム3 |
|
強調イタリック: テキストを1つのアスタリスク(*)または1つのアンダースコアでラップします。 |
*テキスト* _さらにテキスト_ |
テキスト さらにテキスト |
|
強調太字: テキストを2つのアスタリスク(*)または2つのアンダースコアでラップします。 |
**テキスト** __さらにテキスト__ |
テキスト さらにテキスト |
|
インライン・コード: テキストの周りに開き引用符(`)を使用します。 |
これは`インライン・コード`の例です。 |
これは |
|
コード・ブロック: 各行を4つのスペースでインデントします |
事前フォーマットされたコードのブロックをフォーマットします: これはコード行です。 |
事前フォーマットされたコードのブロックをフォーマットします:
|
|
リンク: リンク・テキストを大カッコ内に入れて、すぐ後にURLをカッコ内に入れたものを続けます。 |
これは[リンクの例]です(http://example.com)。 |
これはリンクの例です。 |
Markdownの詳細は、What is Markdown?を参照してください。
診断情報の取得
レスポンス・コードと返されたデータを確認して、エンドポイントが有効化どうかを判断できます。 2xx以外のレスポンス・ステータスが、必ずしもテストが失敗したことを意味するわけではありません。 操作がNullレスポンスを返すと想定される場合、レスポンスは4xxコードを示します。
送信するすべてのメッセージについて、MCSは相関IDでタグ付けします。 相関IDは、リクエストと他のロギング・データを関連付けます。 相関IDには、各リクエストに一意の実行コンテキストID (ECID)が含まれます。 ECIDとリレーションシップID (RID)により、ログ・ファイルを使用してOracle Fusion Middlewareコンポーネント間でメッセージを相互に関連付けることができます。 複数のメッセージを調べることで、問題が発生した場所を容易に特定できます。 たとえば、呼出しのECIDを使用して、Oracle Fusion Middlewareロギングからレコードを取り出すことができます。 Administrationページで「Logs」をクリックして、ロギング・データを表示します。
MCSのアクセス権に応じて、あなたまたはあなたのモバイル・クラウド管理者は、「リクエスト履歴」ページでAPIエンドポイントのクライアントとサーバーのHTTPエラー・コードを表示することができ、原因をトレースしようとしているときのメッセージ・ステータスのコンテキストを見ることができますエラー。 送信されるすべてのメッセージには、イベント発生時刻、メッセージID、リレーションシップID (RID)、実行コンテキストID (ECID)などの属性セットがあります。
診断の取得およびその説明の詳細は、パフォーマンスのモニタリングおよびトラブルシューティングを参照してください。
カスタムAPIを構成したら、API実装を提供できます。すなわち、独自のカスタム・コードを作成し、モバイル・バックエンドに追加してAPIにアクセスします。 カスタムAPIの実装を参照してください。
API設計の考慮事項
カスタムAPIを構成する際、正しい形式のAPIであることを保証するために、すなわち、URLおよびリソースが正しい形式であり、合理的な読取りおよび接続タイムアウトが設定され、RAMLファイルを提供する場合は正しく構成されていることを保証するために、実行できることがいくつかあります。
次に、APIおよびAPIを改良するために使用できるより高度な構造体の詳細な説明を構成する際に考慮すべきことをいくつか示します。
有効なURL
RESTful APIを作成する場合、有効なURLを定義することが重要です。 APIのURLは、指定するAPI名および追加するリソースやメソッドから定義する際に確認できます。 有効なURLにするには、次のベスト・プラクティス・ガイドラインに準拠する必要があります。
-
関係のある容易に識別可能なリソース名を指定します。 URLに識別子を使用することで、クエリー文字列を使用するよりもリソースがわかりやすくなります。 リソース名
/customers/2223または/customers/api?type=customerid=2223?は、どちらが理にかなっています -
リソースはコレクションにグループ化できるため、コレクション・リソース名をコレクションの参照に使用する属性名と一致させます。
たとえば、属性がお気に入りのブックマークのコレクションである場合、
favoriteLinksの代わりにfavoriteBookmarksという名前のコレクションを明示してください。 -
リソース名を常に複数の名詞にし、複数の名詞と単一のリソース識別子(rid):
/services/1.0/items/{rid}/subitems/{rid}/例えば:
/customers/2223/orders/555APIが同期互換性を持つようにするには、前の例に示すように、関連するリソース名の直後に識別子を置きます。ここで、
2223は特定の顧客の指定であり、555は特定のオーダーの指定です。 特定の顧客がこのように見えることを示すURLが正しくない:/customers/orders/2223/555または/customers/orders/locations/2223。 -
リソース名には小文字を使用し、属性名にはキャメル・ケースを使用します。
例えば:
/services/1.0/items?limit=10&totalResults=true -
一部のブラウザには制約があるため、リソース識別子は32文字以下にします。
-
URLはできるだけ短くします。 まとまりのない長いURLは読みにくく、さらにデバッグするのが困難です。
-
URLを定義する際は、必要に応じて具体的または抽象的にできますが、中カッコ{}の注釈を使用してURIパラメータを示す必要があります。 これにより、対応するRAMLがより詳細になり、テストしやすくなります。
-
すべての日付形式が形式になっていることを確認:
YYYY-MM_DD[THH:mm:ss.sss]Z。例えば:
2014-10-07T18:35:50.123Z -
ページングの場合は、
limitおよびoffset問合せパラメータを使用して、同期ライブラリがページングされたダウンロードを正しく使用するようにします。 ページ区切りのサポートが不要な場合は、これらのパラメータを指定する必要はありません。 -
同期の互換性を確保するには、
orderBy問合せパラメータを使用して並べ替えを指定します。 例えば:“orderBy=propA,propB:desc,propC:asc”。 この例では、デフォルトのソート順序は昇順です。同期互換のカスタムAPIの設計の詳細については、「カスタムAPIの同期化」を参照してください。
-
URLエンコードされているJSON文字列として問合せパラメータに値を指定します。 次に例を示します。
[ { "property":"propertyName", //Supports Equals, NotEquals, LessThan, GreaterThan, LessThanOrEqual,GreaterThanOrEqual "comparison":"Equals", "value":"Must be a string", }, { "property":"Another clause, only support ANDS not ORs", ... } ]
APIタイムアウト
ストリームまたは接続のタイムアウトが原因で、APIが失敗することがあります。 ストリームのタイムアウトは、サーバーへの接続が成功した後、データを転送中に、すべてのデータが送受信される前にネットワークがタイムアウトした場合に発生します。 接続タイムアウトは、ネットワーク接続が行われなくなったときに発生します。
コネクタに接続のための十分な時間を確保し、データを転送できるようにするために、HTTP読取りおよび接続タイムアウトはAPIタイムアウトよりも小さい値にする必要があります。
Network_HttpRequestTimeout値は、操作がタイムアウトする前にHTTPリクエストの送信に費やされた時間を決定します。 デフォルト値は40,000ミリ秒です。 このポリシーの値は、APIのタイムアウト値(ポリシーの値より小さい必要があります)に影響を与えることがあります。 ポリシーの値は、特定の環境に固有であることに注意してください。 開発環境のこのポリシーの値は、ランタイム環境の値とは異なる場合があります。 モバイル・クラウド管理者は、「Administration」タブでタイムアウト値を増減できます。
モバイル・クラウド管理者権限を持っている場合は、管理ビューで環境を選択し、policies.propertiesファイルをエクスポートして、現在の環境ポリシーとその値のリストを表示できます。 API環境ポリシーおよびポリシー設定については、「Oracle Mobile Cloud Service環境ポリシー」を参照してください。 環境ポリシー全般については、「環境ポリシー」を参照してください。
APIリソース
リソースはAPIの重要な要素です。 リソースはエンティティまたはエンティティ・セットへの概念上のマッピングで、相対ベースURIによって識別されます。 言い換えれば、リソースは情報の送信先または受信元アドレスにあるもの(名詞)です。 リソースに対して実行される少なくとも1つのメソッド(動詞)があります。 メソッドは、リソースを表現したものの取得、作成、更新または削除に使用されます。 たとえば、GET incidentsです。
最上位リソースは、ルート・レベルで定義されたリソースです(ルート・リソースとも呼ばれます)。 他のリソースの子として定義されたリソースは、ネストされたリソースです。 ネストされたリソースにより、親リソースの側面を指定できます。 ネストされたリソースは、親リソースURIに相対するURIによって識別されます。 たとえば、rootリソースが.../incidentsとして定義され、ネストされたリソース{id}があるとします。 RAMLでのAPI定義は次のようになります。
title: FIFIncidentReports
version: 1.0
baseURI: /mobile/custom/fif-incidentreport
protocols: [HTTPS]
mediatType: "application/json"
/incidents:
displayName: Incident Reports
get:
description: |
Retrieves all incident reports.
.
.
.
/{id}:
uriParameters:
id:
displayName: id
description: |
The unique id of the incident report.リソースはルート・リソースであれネストされたリソースであれ、常に先頭にスラッシュ(/)が付けられます。 有効なRAMLドキュメントの構築については、「RAML」を参照してください。
リソースがオブジェクトのコレクションで、ネストされたリソースがそのコレクションのアイテムであると考えると、リソース・パスは親リソースを複数形フォームで示し、ネストされたリソースを単数形フォームで示します。 次に例を示します。
.../mobile/custom/fif-incidentreport/incidents/{id}ルート・リソースはincidentsで、インシデントのインスタンスは{id}です。 Endpointsページでリソースに読みやすい表示名を付けることができます。 表示名を指定しない場合、リソースURIが名前として使用されます。
リソースを設計する際の一般的な習慣は、PUTとPOSTメソッドがリクエストで送信されたものと同じオブジェクトを返すようにすることです。
URIパラメータ
相対ベースURIの値を変更または制限するAPIコールを許可する場合は、ベースURIパラメータを設定して上書きできます。 リソースのURIには、可変要素であるパラメータ、たとえば{id}を含めることができます。
リソースのように、パラメータは名前を持つことができます。 fif-incdentreportに対して生成されたRAMLは、idという名前のリソース・パラメータ、表示名(表示名はパラメータ名と同じでなくてもかまいませんが)、表示名(この例ではinteger ):
/{id}:
uriParameters:
id: displayName: id
description: |
the unique id of the incident report
type: integer
required: true
get:
description: |
Retrieves the incident report with the specified id.リソース名の後にパス・パラメータを配置します。 セミコロンを使用して、複数のパラメータを区切ります。 複数の値を設定できるパラメータの場合は、値をカンマで区切ります。
この例では、URIパラメータ/{id}は、ID番号で特定のインシデント・レポートを識別する変数です。 このパラメータには、プロパティdisplayNameとtypeが含まれています。 URIは次のようになります。
.../fif-incidentreport/incidents/{id}パラメータidの値が1234の場合、結果のURIは次のようになります:
.../fif-incidentreport/incidents/1234パラメータは、子(ネストされた)リソースとしてURIパスの一部として、または問合せとして追加できます。 パラメータをURIパスに追加するか、パラメータを問合せに追加するかについて、厳格なルールはありません。 パラメータがリクエストに不可欠かどうかは、検討事項の1つです。 たとえば、特定のレポートのデータを取得するには、以前のfif-incidentreport URIの例に示すように、URIパス内のリソースの識別子(id)を使用します。
ただし、データを絞り込むためにパラメータをフィルタとして使用する場合は、問合せに追加します。 たとえば、technicianを問合せパラメータ.../fif-incidentreport/incidents?technician=joeとして使用すると、特定の技術者だけがレポートをフィルタリングできます。
同期互換性のためのエンドポイントの要件
カスタムAPIがクライアント上の同期ライブラリによって使用されているときに最適なデータ同期を実現するには、カスタムAPIに特定のサーバー側エンドポイントのセットが含まれている必要があります。
たとえば、Departmentレコードのコレクションを返し、同期ライブラリを使用するクライアントによって消費されるカスタムAPIエンドポイントが定義されているとします。 レコードは、コレクション・エンドポイント/Departmentsから取得され、ライブラリによってクライアントのローカル・キャッシュに保管されます。 その後、ライブラリは、期限が切れた(/Departments/Financeと/Departments/HR)ので、更新が必要なキャッシュ内の2つのレコードを識別します。
この場合、最新のデータを取得するために、同期ライブラリはコレクション全体ではなく、更新が必要なレコードのみを取得します。
サーバー側では、関連する同期ライブラリを介して、これらのエンドポイントはクライアントに代わって個別に呼び出されます。 データは単一のペイロードおよびレスポンスでクライアントに返されるため、必要なオブジェクトごとに取得を複数行う必要がありません。
これをサポートするために、同期ライブラリでは、カスタムAPIにコレクション・リソース(GET /{collection})とオブジェクト・リソース(GET /{collection}/{objectId})の両方のGETメソッドが含まれている必要があります。 つまり、このDepartmentの例では、次のエンドポイントが必要になります。
-
GET /Departments -
GET /Departments/{DeptId}
ステップをさらに進めるには、取り出されたオフラインAPIコレクション・オブジェクトをオブジェクトの追加、更新、削除などで変更できる場合、同期ライブラリは適切なカスタム・コードAPIを呼び出してオブジェクトの変更をサーバー側。 オブジェクトの作成、更新または削除をサポートするには、次のタイプのエンドポイントがサーバー側のカスタムAPIで実装されている必要があります。
-
GET /{collection} -
GET /{collection}/{objectId} -
PUT /{collection}/{objectId} -
POST /{collection} -
DELETE /{collection}/{objectId}
PUT、POST、およびDELETE操作の組み込みはオプションです。 たとえば、アプリケーションがコレクション内のオブジェクトを削除しない場合は、DELETE操作を実装する必要はありません。
注意:
同期ライブラリは、PATCH操作をサポートしていません。
同期互換のカスタムAPIの構成の詳細については、「カスタムAPIの同期化」を参照してください。
スキーマ
JSONスキーマは、APIの構造をJSONベースのデータ形式で定義します。 JSONスキーマを使用してJSONデータを検証できます。 スキーマはSchemaページで定義できます。 IncidentReportsの例のスキーマを見てみましょう:
{
"$schema": "http://json-schema.org/draft-04/schema#",
"type": "array",
"description": "Incident Reports array",
"items": {
"type": "object",
"properties": {
"id": { "description": "Unique id for the incident report",
"type": "integer" },
"title": { "description": "Title for the incident report",
"type": "string" },
"createdon": { "description": "Date and time of creation",
"type": "string" },
"contact": { "decription": "Contact information for customer filing the report",
"type": "object",
"properties": {
"id" : { "description": "Unique id for the customer",
"type" : "string" },
"name" : { "description": "First and last name of contact",
"type" : "string" },
"street": { "description": "Street address of contact",
"type" : "string"},
"city" : { "description": "City of contact",
"type" : "string"},
"postalcode" : { "description" : "Postalcdoe of contact",
"type": "string" }
}
},
"status" : { "description": "The current status of the incident",
"type" : "string" },
"priority" : { "description": "The current priority of the incident",
"type" : "string" },
"driveTime" : {"description" : "Calculated field based on location",
"type" : "integer"},
"imageLink" : { "description" : "Link to image from Storage",
"type": "string" }
},
}
}このスキーマには次のキーワードが含まれます。
-
$schema: このスキーマがv4のドラフト仕様に基づいていることを示します。 JSONスキーマのルートに配置されている必要があります。 このキーワードはJSONスキーマに必ず含める必要があります。 -
type: JSON制約を定義するので、データは配列でなければなりません。 -
description: スキーマの内容を記述します。 -
items: 配列内のアイテムを定義します。 インシデント・レポートでは、各レポートに属性を割り当てることができます。 この例では、すべてのアイテムのタイプがobjectであり、各オブジェクトには、レポートID、タイトル、連絡先情報、ステータス、優先度などのプロパティのセットがあります。
JSONスキーマで使用するキーワードの完全なリストについては、http://json-schema.org/を参照してください。
APIのスキーマを追加するには、「スキーマの指定」を参照してください。
RAML
MCSインタフェースを使用してAPIを作成すると、API定義はRAMLドキュメントとして保存されます。 RAMLは、RESTful APIを記述する簡単で効率的な方法です。 RESTはRepresentational State Transfer (REST)を表し、単純なHTTPコールを使用してサーバー上で基本的な操作(作成、読取り、更新または削除)情報を実行する手段です。
最初から作成したRAMLドキュメントをAPI Designerにアップロードすることもできます。 API Designerは渡された入力を受け取って、カスタムAPIの内容を記述するRAMLファイルを作成します。 RAMLはAPIそのもののみを定義し、APIの実装は定義しません。 APIを実装するには、JavaScriptを使用してカスタム・コードを作成する必要があります。 APIの実装方法の詳細は、「カスタムAPIの実装」を参照してください。
注意:
モバイル・バックエンドのナビゲーション・リストから「APIs」をクリックしてAPIページに移動した場合、RAMLドキュメントをアップロードする機能は使用できません。 RAMLファイルをアップロードすると、必要な名前フィールドの値がRAMLファイルから抽出されます。 簡単な説明は追加する必要があります。 RAMLファイルには、少なくとも、API名、ベースURI (/mobile/custom/ apiname)、およびバージョン番号が含まれている必要があります。
RAMLファイルを有効なものにするには、メディア・タイプ、ベースURI、HTTPSプロトコルおよびバージョン番号を指定する必要があります。
#%RAML 0.8
---
title: api_title
version: 1.0
protocols: [HTTPS]
baseURI: /mobile/custom/api_name
mediaType: application/json注意:
MCS カスタムAPIにはHTTPSプロトコルが必要です。 HTTPプロトコルを使用してAPIを構成するRAMLドキュメントをアップロードした場合、HTTPSを使用するように自動的に編集されます。
新しいAPIの場合、モバイル・クラウド管理者がAsset_DefaultInitialVersion環境ポリシーの値を変更していない限り、構成を保存すると、デフォルトのバージョン1.0が自動的に適用されます。 ただし、API構成をアップロードした場合、表示されるバージョン値はファイルから取得されます。
注意:
バージョン値には特定の形式が使用されます。 バージョンは整数で指定されます。 たとえば、RAMLファイルでは、version: 2.0は有効ですが、version: v2.0は有効ではありません。
RAMLを使用すると、リソースやメソッドを記述するためのリソース・タイプと特質を定義でき、設計で繰返しが削減されることで、RESTful APIがより簡潔になります。 RAML (.raml)ドキュメントの主なコンポーネントは次のとおりです:
-
APIの基本情報:
-
API表示名: APIリストに表示されるAPIの読みやすい名前(例:
FIFIncident Reports) -
ベースURI: リソースのアドレス(カスタムAPIの場合は
/mobile/custom) -
API名: 構成内のAPIの名前(
fif-incidentreport) -
簡単な説明: APIの簡単な説明
-
-
リソースを特徴づけてAPI定義で不必要な繰返しを避けるための、リソース・タイプおよび特質。
-
リソース(1つ以上のエンティティへの概念的なマッピング)、リソース・メソッドおよびスキーマ
RAMLドキュメントを正しく構成するためのヒントを次に示します:
-
RAMLはHTTPプロトコルとHTTPSプロトコルの両方を許可しますが、MCSではカスタムAPIにHTTPSプロトコルが必要です。 HTTPプロトコルを使用してAPIを構成するRAMLドキュメントをアップロードした場合、HTTPSを使用するように自動的に編集されます。
-
空白の相対URI (すなわち、/:)で最上位リソースを定義した場合、サブリソースは追加できません。
エラー・メッセージで、構造が無効であることが警告されます。 たとえば、次のリソース定義は失敗します。/: /reports:レポートを最上位リソースにする必要があります。/: /reports: -
最上位リソースに空の相対URIサブリソースを含めることはできません。例を示します。
/books: /: -
重複するパスを作成することは避けてください。例を示します。
/reports/{id}: /reports: /{id}:リソース名に複数のサブリソースを含めるのは有効です。 次に例を示します。/reports: /county/branchid/reportissue: -
プロパティの
description:フィールドにのみコメントを追加します。 RAMLソース・エディタでは、コメント行(たとえば、#report issue by technician)を使用してコメントを追加することはできません。 コメント行に追加されたコメントは、パーサーによって削除されます。
RAMLの詳細については、http://raml.org/を参照してください。
カスタムAPIの編集
ドラフト状態であれば、いつでもAPIを編集できます。 公開済のAPIは変更できません。
- をクリックして、サイド・メニューから「Applications」→「APIs」を選択します。少なくとも1つのカスタムAPIが存在するため、APIsページが表示されます。
- 必要に応じて、一般情報、リソース、スキーマ、特質、タイプおよびセキュリティ・ポリシーの各フィールドを編集します。リソースのメソッドを作成するたびに、そのメソッドのアイコンが「Methods」ページの上部に表示されます。 これらのアイコンの1つをクリックすると、そのメソッド定義に直接移動します。「Resources」ページでは、リソースに定義されているメソッドのアイコンは「Methods」ナビゲーション・リンクの下に表示されます。 どのタイプのメソッドがリソースに定義されているかをすぐに確認できます。 アイコンをクリックすると、そのメソッド定義に移動します。
いつでも「Save and Close」をクリックして現在の変更内容を保存し、残りの変更は後で終わらせることができます。
編集したバージョンは引き続きドラフト状態であり、構成に納得するまでカスタムAPIの編集を続けることができます。 その時点で、カスタムAPIを公開できます。 「カスタムAPIの公開」を参照してください。 公開済のAPIに変更を加える必要がある場合は、新規バージョンを作成する必要があります。 APIの新規バージョンの作成を参照してください。
APIを公開したら、他の環境にデプロイできます。 APIライフサイクルの特定の部分の詳細は、「API ライフサイクル」 を参照してください。 MCSのライフサイクルに関する一般的な情報は、「ライフサイクル」を参照してください。
カスタムAPIのトラブルシューティング
フィールドに誤った値が入力されると、メッセージ・ウィンドウにエラーと、フィールドに応じて使用する適切な構文または値タイプが表示されます。 場合によっては(不正なスキーマまたはRAMLがアップロードされた場合など)、エラー・メッセージに、エラーの説明を示す「Show Details」リンクが含まれることがあります。 「ログ・メッセージの表示」を参照してください。
カスタム・コードの構成時に発生する可能性のある一般的なエラーの詳細は、「一般的なカスタム・コード・エラー」を参照してください。
-
ソーシャル・アイデンティティを使用してAPIにアクセスした場合、認証ヘッダーに入力されたプロバイダのアクセス・トークンは、ターゲット・モバイル・バックエンドのプロバイダのアクセス・トークンでなければなりません(つまり、元のモバイル・バックエンドがあったモバイル・バックエンド・リダイレクト)。
-
APIがモバイル・ユーザーによってアクセスされた場合、ユーザーはターゲット・モバイル・バックエンド(元のモバイル・バックエンドがリダイレクトされるモバイル・バックエンド)に関連付けられたレルムのメンバーでなければなりません。