フェードRESTサービス用のカスタムAPIの実装

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

可能な場合には、外部バックエンド・サービスとユーザー・インタフェースの間にファサードのAPIレイヤーの構築を開始して、バックエンド・サービスへのコール数をできるかぎり減らすことをお薦めします。たとえば、モバイル・アプリケーションで、他のRESTサービスへのコールを処理し、モバイル・アプリケーションへの1つのレスポンス内のすべての受信データを統合するfa ade APIレイヤーへの単一のコールを実行できます。

完全なカスタムAPIの作成

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

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

エンドポイントの定義

APIのエンドポイントを定義するリソースを作成します。リソースはAPIのクラックスです。これには、タイプ、データに関連付けられているもの、他のリソースとの関係、およびそれを処理する1つ以上のメソッドが含まれています。リソースは、ほぼすべて(イメージ、テキスト・ファイル、他のリソースの集合、論理トランザクション、プロシージャなど)です。

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

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

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

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

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

「圧縮モード」(新規リソースの右側)に切り替えると、リソースを簡単に見つけられます。コンパクト表示では、リソースの説明、リソース・タイプおよびパスは非表示になります。

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

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

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

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

メソッドを選択した後は、リソースごとにメソッドを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がデフォルトで表示されますが、これが目的のコードではない場合は、ドロップダウン・リストからステータス・コード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)の場合、提供するスキーマまたは属性がないため、何もする必要はありません。

次の例は、新規リソースが正常に作成されたことを示すステータス・コード201を使用して、auditsリソースのPOSTメソッドに対するレスポンスが作成されたことを示しています。この例では、戻りレスポンス形式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に追加されます。「API名」フィールドの下にベースURIが表示されます。
  
  このコネクタAPIの新規バージョンではなく、同じリソース名を他のコネクタAPIに含めることはできません。
3. 簡単な説明:この説明は、このAPIを選択したときにConnectorsページに表示されます。
「作成」をクリックします。
「RESTコネクタAPI」ダイアログ・ボックスの「一般」ページで、タイムアウト値を設定します。
- HTTP読取りタイムアウト:データ読取りの待機に要する最大時間(ミリ秒)。値を指定しない場合は、デフォルト値の20秒が適用されます。
- HTTP接続タイムアウト:リモートURLへの接続に要した時間(ミリ秒)。0mmsの値は、タイムアウトが無限であることを意味します。
  
  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には、1つのポリシーのみを選択します。選択したポリシーの説明がリストの下に表示されます。
デフォルト値を使用しない場合は、選択したポリシーにオーバーライドを指定します(該当する場合)。
プロパティを上書きするには、デフォルト以外の値を入力または選択します。
「保存」をクリックして作業を保存するか、「保存してクローズ」をクリックして作業を保存し、RESTコネクタAPIウィザードを終了します。
「次へ」(>)をクリックして、次のステップに進みます。