Faier REST ServiceのカスタムAPIの実装

モバイル・アプリケーションを開発する場合、通常はユーザー・インタフェース・レイヤーから最初に開始し、次にREST Webサービスを使用して、アプリケーションを別のアプリケーションに接続します。この方法は、小規模アプリケーションや単純アプリケーションに有効です。アプリケーションが大きいときに複数のバックエンド・サービスに接続する場合は、パフォーマンスおよびセキュリティの問題を不注意に取り入れることができます。

外部バックエンド・サービスとユーザー・インタフェースの間にfaier APIレイヤーを構築すると、可能な場合は常にバックエンド・サービスへのコール数を減らすことがベスト・プラクティスです。たとえば、モバイル・アプリケーションでは、他のRESTサービスへのコールを処理するファクタドAPIレイヤーへの1回のコールを実行し、すべての着信データを1回のレスポンスでモバイル・アプリケーションに統合できます。

完全なカスタムAPIの作成

Oracle Mobile Hubを使用して完全なカスタムAPIを作成する手順:

をクリックし、サイド・メニューから「開発」、「api」の順に選択します。APIがすでに作成されている場合(ドラフト状態か公開済状態かに関係なく)、APIのリストが表示されます。カスタムAPIが存在しない場合、「新規API」ボタンのあるページが表示されます。すでに作成したAPIをクリックするか、「新規API」をクリックして開始します。

エンドポイントの定義

リソースを作成してAPIのエンドポイントを定義します。リソースとは、APIの重要性のことです。データ型、データが関連付けられているデータ、他のリソースとの関係、そのデータに対して実行される1つ以上のメソッドが含まれていること。リソースには、イメージ、テキスト・ファイル、他のリソースの集合、論理トランザクション、手順など、ほぼすべてがあります。

「エンドポイント」ナビゲーション・リンクをクリックして開始します。
「新規リソース」をクリックし、いくつかの基本情報を追加します。

「新規リソース」をクリックするたびに、最上位レベル(ルート)のリソースを作成します。子(ネストされた)リソースを追加する場合は、最上位レベルのリソースの横にある「追加」(+)をクリックします。Xをクリックして、リソースを削除します。

注意:
「メソッド」リンクの下にあるアイコンを参照してください。リソースのメソッドを定義するたびに、そのメソッドのアイコンが「メソッド」リンクの下に表示されます。これらをショートカットとして使用し、リソースにすでに定義されているメソッドを確認します。アイコンをクリックすると、「メソッド」ページの定義に直接移動します。
リソース・パスを指定します。これは、URI (ベースURIに対する相対パス)です。たとえば、ベースURIが/mobile/custom/audit/である場合、リソース、調査結果、つまり/mobile/custom/audit/findを追加できます。
表示名を指定します。リソースの名前で、APIドキュメント内で簡単に識別できるようにします。
リソースは、APIテスト・ページの左側にある表示名によってリストされます。
リソースの簡単な説明を入力します。

説明を入力すると、説明フィールドの下にURIが表示されます。
(オプション)リソース・タイプ(resourcesType:)であるRAMLリソース・タイプを指定します。リソース・タイプの指定は必須ではありません。リソース・タイプを使用するが、リソース・タイプが定義されていない場合は、「タイプ」リンクをクリックし、定義します。

リソースのメソッドを作成すると、そのメソッドのシンボルが「メソッド」リンクの下に表示されます。リソース定義の調査が必要な場合は、リソースに定義されているメソッドをすぐに確認できます。アイコンをクリックすると、そのメソッド定義に直接移動します。

「Compact Mode」(「New Resource」の右にある)に切り替えることで、すっきりさせてリソースをより迅速に見つけることができます。コンパクト表示では、リソースの説明、リソース・タイプおよびパスが非表示になります。

リソースへのメソッドの追加

メソッドは、リソースに対して実行できるアクションです。「メソッド」ページには、一度に1つのメソッドが表示されます。2つ以上の方法を定義した後、ページの上部にあるメソッドのアイコンをクリックしてその詳細を表示できます。

「メソッド」をクリックして、リソースにメソッドを追加します。

メソッドを定義しているリソースにパス・パラメータがある場合は、それらが「メソッドの追加」の上に表示されます。
1. (オプション)各メソッドを使用してパス・パラメータを渡す場合は、「必須」をクリックします。
  パラメータ名が表示されます。
2. パラメータの表示名とサンプル・コードを指定します。
3. ドロップダウン・リストから、パラメータの有効な値タイプを選択します。
「メソッドの追加」をクリックし、目的のメソッドを選択します。

メソッドは1つのリソースで1回のみ使用するため、メソッドを選択すると、そのメソッドはメソッド・リストには表示されなくなります(たとえば、1つのリソースに2つのDELETEメソッドを定義することはできません)。定義したそれぞれのメソッドのアイコンがページの上部に表示されます。メソッドのアイコンをクリックすると、その定義に直接移動できます。
(オプション)「説明」フィールドにメソッドの簡単な説明を入力します。
(オプション)メソッドの表示名を入力します。
(オプション)メソッドに適用するトレイトを指定します。

リソース特性が定義されていない場合は、「エンドポイント」をクリックしてメインの「リソース」ページに戻り、「トランザクション」リンクをクリックして定義します。そのツールを使用して、類似する操作のコレクションを定義できます。

リソースのメソッドを定義したら、それらのメソッドのリクエストとレスポンスを定義できます。

メソッドのリクエストの定義

メソッドを選択したら、接続するサービスに対するリクエストを定義します。たとえば、POSTメソッドを選択した場合、作成する内容を定義できるようになりました。それには、パラメータおよびサービスに送信するデータの説明を含むリクエスト本文を追加します。

「リクエスト」をクリックして、リクエストを定義します。
「パラメータの追加」をクリックし、パラメータ・タイプ「問合せ」または「ヘッダー」を選択します。メソッドにパラメータが必要な場合は、「必須」を選択します。
1. パラメータに名前および表示名を指定します。
2. 有効な値タイプ(文字列、数値、整数、日付またはブール)を選択してください。
3. (オプション)エンドポイントの妥当性のテスト時にパラメータの説明および使用可能な例を指定します。たとえば、リソースauditsがあり、問合せパラメータauditorID (数値)と、文字列値を取る別のパラメータauditNameを追加する場合は、次のようになります。
```
/audits: 
  get: 
    description: | 
      Gets list of audits, organizations etc.     
    queryParameters: 
      auditorID:  
        id: Auditor ID
        description: | 
          display auditor identifier 
        type: integer 
        example: |
          1234
        required: false      
      auditName:
        displayName: auditName
        description: |
          Audit name
        example: "Payroll Process Audit"
```
  この例では、GETメソッドが問合せパラメータauditorIDおよびauditNameで定義されています。
4. (オプション)「その他のプロパティ」をクリックし、ネストされたプロパティをパラメータに追加します。「繰返し」をクリックして、現行のパラメータの倍数を追加します。
5. 「パラメータの追加」をクリックして、メソッドの別の最上位レベル・パラメータを追加します。
選択した方法に応じて、「メディア・タイプの追加」をクリックし、メソッド本体を定義します。本文には、サーバーに送信するデータが含まれています。たとえば、POSTメソッドを定義する場合は、新規顧客リストやサービス要求など、作成するアイテムを定義する必要があります。GETメソッドを定義している場合、メソッド本体を送信する必要はないため、メディア・タイプを指定する必要はありません。
1. メソッド本体のメディア・タイプを選択します。これは、テキスト、イメージ、Webフォームなど、送信するメッセージの形式です。
  タイプ(イメージ・タイプのスキーマを入力しないなど)に応じて、スキーマまたは例、あるいはその両方を追加するオプションがあります。
  スキーマを定義するときは、リソースの目的に必要なデータのみを追加します。つまり、送信の速度を低下させるだけの不要なデータを追加しないで、エラーが発生する可能性があります。
2. (オプション)「スキーマ」をクリックし、エディタ・ペインにスキーマを(JSON形式で)入力します。スキーマが本文のテンプレートに類似しています。メッセージのコンテンツの定義に使用するものです。
3. (オプション)「例」をクリックし、エディタ・ペインに例(JSON形式)を入力します。このペインは、モック実装がメソッドのモック応答として使用します。モック・データを使用すると、メソッドの動作を確認しやすくなります。この例は、auditsリソースのPOSTメソッドで定義されている、メッセージ本文で送信されるデータのモック値を示しています。
```
body: 
  application/json: 
    example: | 
      { 
        "Title": "Leaking Water Heater",
        "Username": "joh1017",  
        "imageLink": "storage/collections/2e029813-d1a9-4957-a69a-fbd0d7431d77/objects/6cdaa3a8-097e-49f7-9bd2-88966c45668f?user=lynn1014", 
        "Notes": "my water heater is broken"
      }                               
```
メディア・タイプを追加するには、「メディア・タイプの追加」をクリックします。メソッドが不要と判断した場合は、バナーの「X」をクリックして削除します。

メソッドに対するレスポンスの定義

要求によっては、応答が必要な場合と不要な場合があります。レスポンスは、サービスから結果を返すプロセスを説明します。リクエストしたデータが返されたことを確認するレスポンス、またはリクエストが受信されたかどうかを確認するレスポンスを定義できます。レスポンスの定義は、リクエストの定義に似ています。主な違いは、接続の結果を知らせるためにステータス・コードを選択する必要があることです。

「レスポンス」をクリックして、1つ以上のレスポンスを定義します。
「レスポンスの追加」をクリックし、返されるステータス・コードを選択します。
ステータス・コード200がデフォルトで提供されていますが、これが目的のコードでない場合は、ドロップダウン・リストからいずれかを選択します。
- 2 xxは接続に成功したことを示します。
- 3 xxはリダイレクトが発生したことを示します。
- 4 xxは、ユーザー・エラーが発生したことを示します。
- 5 xxは、サーバー・エラーが発生したことを示します。
APIを使用して構成中のAPIで発生する可能性のあるエラーの理由を把握できるように、HTTPステータス・コードを使用してエラーの状況に最も適したコードを返すことができます。
コードが指定する内容の説明を入力します。
「ヘッダーの追加」をクリックして、レスポンス・ヘッダーまたは問合せを選択し、ヘッダーまたは問合せの名前、ヘッダーの表示名、およびヘッダーの有効な値のタイプを指定します。
「メディア・タイプの追加」をクリックし、レスポンスの形式を選択します。選択したメディア・タイプに応じて、リクエスト本文での場合と同様に、パラメータ、スキーマまたは例を追加できます。
1. テキストベースのメディア・タイプ(application/jsonまたはtext/xmlなど)に対して、「スキーマ」をクリックして、本体にスキーマを(JSON形式で)入力します。
  リクエスト本文と同様に、関連するデータのみをレスポンス本文に追加します。操作に実際に必要なデータよりも多くのデータを含めないでください。
2. 「例」をクリックして、レスポンス本文にモック・データ(JSON形式)を追加します。実際のデータでテストする前に、モック・データを使用してメソッドの動作を検証します。
3. フォームベースのメディア・タイプ(たとえば、multipart/form-data)の場合、「パラメータの追加」をクリックし、パラメータが必須の場合は「必須」を選択します。次に、名前を指定して、値タイプを選択します。オプションで、パラメータの名前を指定できます。
4. イメージベースのメディア・タイプ(image/pngなど)の場合、指定するスキーマまたは属性がないため、何も実行する必要はありません。

次の例は、auditsリソースの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デザイナの別のページに進むと、ルート、リソース・タイプまたはトレイトを作成したり、APIドキュメントを追加できます。

メソッドが不要と判断した場合は、バナーの「X」をクリックして削除します。

RESTコネクタAPIの作成

コネクタAPIの作成、構成およびテストには、RESTコネクタAPIウィザードを使用します。

基本的な作業コネクタAPIを取得するには、コネクタAPIの名前と外部サービスのURLを、ほとんど指定しません。

そこから次のことができます。

アクセスするデータに対する特定のリクエストまたはレスポンスを形成するルールを定義します。
アクセスしているサービスに対するクライアント側のセキュリティ・ポリシーを構成します。
接続をテストし、接続に対して行われたコールの結果をテストします。

アプリケーションでコネクタAPIをコールできるようにし、APIおよび実装を自動的に生成できるようにするには、カスタムAPIおよび実装を作成する必要があります。これを手動で行うには、適切なリソースを使用してカスタムAPIを作成してから、カスタム・コードを実装する必要があります。

基本コネクタの設定

RESTコネクタAPIウィザードの最初の2ページを完了して、機能しているコネクタを作成できます。

をクリックし、サイド・メニューから「開発」、「api」の順に選択します。
REST (これが作成される最初のコネクタAPIの場合)または「新規コネクタ」をクリックし、ドロップダウン・リストから「REST」を選択します。
次の情報を指定して、新しいRESTコネクタAPIを識別します。
1. API表示名:コネクタAPIのリストに表示される名前。
2. API名:コネクタAPIの一意の名前。
  
  デフォルトでは、この名前は、コネクタAPIのリソース名として相対ベースURIに追加されます。ベースURIは「API名」フィールドの下に表示されます。
  
  このコネクタAPIの新規バージョン以外では、他のコネクタAPIに同じリソース名を付けることはできません。
3. 簡単な説明:このAPIが選択されている場合、この説明がConnectorsページに表示されます。
「作成」をクリックします。
「RESTコネクタAPI」ダイアログ・ボックスの「一般」ページで、タイムアウト値を設定します。
- HTTP読取りタイムアウト:データ読取りの待機に要した最大時間(ミリ秒)。値を入力しない場合は、デフォルト値の20秒が適用されます。
- HTTP接続タイムアウト:リモートURLへの接続に要した時間(ミリ秒)。0 mmsの値は、タイムアウトが無限であることを意味します。
  
  HTTPタイムアウト値は、デフォルト値40,000ミリ秒のNetwork_HttpRequestTimeoutポリシーより小さい値である必要があります。
  
  注意:
  サービス開発者ロールに加えてモバイル・クラウド管理者ロールがある場合は、policies.propertiesファイルを開くと、管理者ビューから現在の環境のネットワーク・ポリシーの値を確認できます。それ以外の場合は、モバイル・クラウド管理者に値を要求してください。
「ディスクリプタ」をクリックし、サービスの接続情報を入力します。

SwaggerディスクリプタのURLを指定すると、使用可能なリソースが識別および表示され、目的のリソースを選択できます。

注意:
標準のインターネット・アクセス・ポート80および443のみがサポートされます。カスタム・ポートを使用してサービスへの接続を作成することはできません。
「保存」をクリックします。
(オプション)「テスト」をクリックし、認証資格証明を選択して、サービスに対するテスト・コールを実行します。

このページでは、次の方法でコネクタをさらに構成できます。

(ディスクリプタ・ページにディスクリプタを指定している場合)「リソース」ページに移動し、公開されるリソースのメソッドを選択します。
ルールを定義します。
セキュリティ・ポリシーを設定します。

コネクタAPIの構成が有効であることを確認するには、公開する前に、コネクタAPIの「テスト」ページでテストするようにしてください。つまり、このコネクタAPIを使用するカスタムAPI (実装を含む)もテストする必要があります。基本的に、コネクタAPIを公開する準備が整っている場合は、コネクタをコールするカスタムAPIも公開する準備が完了している必要があります。

ルールの設定

モバイル・アプリとサービス間の相互作用を定義するルールを設定します。ルールを使用すると、サービスのリソースへのすべてのコール、特定のプロキシ・パスへのコール、および特定タイプの操作(動詞)に対するコールにデフォルトのパラメータ値を追加できます。これにより、URL文字列の一貫した構文が適用され、カスタム・コード開発者はこれらの値を挿入する必要がなくなり、分析を使用して様々なコールを追跡できます。

1つ以上のルールを作成できます。各ルールには、QueryタイプおよびHeaderタイプのパラメータを1つ以上含めることができます。

適用されているルールがない場合、すべてのコールがプロキシを介して既存のサービスに渡されます。

コネクタがまだ開いていない場合は、をクリックして、サイド・メニューから「開発」→「api」を選択します。
編集するコネクタAPIを選択し、「開く」をクリックします。
「ロール」を選択します。
「新規ルール」をクリックします。
「パラメータの追加」をクリックし、「問合せ」または「ヘッダー」パラメータ・タイプを選択し、問合せ名またはヘッダー名、およびその値を入力します。

注意:

特定のヘッダーをデフォルトで設定するルールを定義できますが、カスタム・コードを使用してコネクタを直接コールしたクライアントや、Webブラウザやモバイル・アプリからなど、間接的に同じヘッダーを設定している場合はルールは適用されません。

特に、リクエスト本文の書式の設定は通常、RESTコネクタ・ルールとしてではなく、Content-Typeヘッダーを含むカスタム・コードで実行されます。同様に、レスポンス本文の書式設定は、RESTコネクタ・ルールとしてではなく、Acceptヘッダーを使用したカスタム・コードでも実行されます。

ルールには、必要な数だけパラメータを追加できますが、操作が多すぎるルールをオーバーロードしない方がよい方法です。単純なルール構成を使用すると、トラブルシューティングを実行できます。
「リソース」を展開し、リモートURLを編集して、適用されるルールのリソースを指定します。基本URL値は、基本情報の設定ステップで入力した値で、編集できません。
「リモートURL」で指定したリソース・レベルのみにルールを適用する場合は、「下位レベルのリソースに適用しない」を選択します。
(オプション)定義したルールに適用しないHTTPメソッドの選択を解除します。デフォルトでは、すべてのメソッドが選択されます。
(オプション)「新規ルール」をクリックして別のルールを作成します。

注意:

別のルールと競合するルールを定義する場合、最初に適用されたルールが優先され、競合するルールは無視されます。

終了したら、「保存」をクリックし、「次へ」(>)をクリックしてコネクタAPIの構成の次のステップに進みます。

定義したルールの説明は、「デフォルト・パラメータ」セクションのすぐ上の「ルール」バナーに表示されます。たとえば、次の値が指定されたとします。

リモートURL = https://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattle
ローカルURI = myMapAPI
次のパラメータを持つルール: Query:key:A3FAEAJ903022
GETおよびPUT HTTPメソッド

ルールの説明は次のようになります。

myMapAPI/directionsで、GETをhttps://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattleに使用できるようにするには、Query:key=A3FAEAJ903022を含めます。

ルールが作成されない場合、説明は次のようになります。

myMapAPIで使用可能なすべてのmethodからhttps://maps.googleapis.com/maps/api/directionsには、デフォルト・パラメータは適用されません。

これで、既存のサービスにマップされるベースURIが作成されました。使用例:

mobile/connector/myMapAPI/directions/json?origin=los+angeles&destination=seattleはhttps://maps.googleapis.com/maps/api/directions/json?origin=los+angeles&destination=seattleにマップされます

セキュリティ・ポリシーの構成およびプロパティのオーバーライド

コネクタAPIをファイナライズする前に、セキュリティの処理方法を検討する必要があります。セキュリティ・ポリシーまたは認可ヘッダーのいずれかを使用できます。推奨される方法は、接続するサービスの認証スキームを記述するセキュリティ・ポリシーを選択することです。

すべてのセキュリティ・ポリシーには、オーバーライドと呼ばれるプロパティがあり、これを構成できます。ポリシー構成プロパティをオーバーライドする理由の1つは、維持するポリシー数の制限です。構成がほとんど変わらない複数のポリシーを作成するのではなく、同じ一般ポリシーを使用し、要件に一致するように特定の値をオーバーライドできます。

セキュリティ・ポリシーを選択し、ポリシー・オーバーライドを設定するには、次のようにします。

コネクタがまだ開いていない場合は、をクリックして、「開発」を選択してから、サイド・メニューから「api」を選択します。
編集するコネクタAPIを選択し、「開く」をクリックします。
「セキュリティ」を選択します。
使用可能なポリシーのリストからセキュリティ・ポリシーを選択し、右矢印をクリックして「選択したポリシー」リストに移動します。
コネクタAPIの単一のポリシーのみを選択してください。選択したポリシーの説明がリストの下に表示されます。
デフォルト値を使用しない場合、選択したポリシーに対してオーバーライドを指定します(該当する場合)。
プロパティをオーバーライドするには、デフォルト以外の値を入力または選択します。
「保存」をクリックして作業を保存するか、「保存してクローズ」をクリックして作業を保存し、RESTコネクタAPIウィザードを終了します。
「次へ」(>)をクリックして、次のステップに進みます。