Skip to main content

 

 

 

 

Template:OutSystems/Documentation_KB/Breadcrumb_New_Layout

 

Template:OutSystems/OSLanguageSwitcher
Language:

 

 

 

 

 
OutSystems

OutSystemsでのSAP ODataサービスの利用

OutSystemsでSAP ODataサービスを利用するには、以下の手順を実行する必要があります。

  1. SAP API Business Hubからサービス仕様ファイルを取得する
  2. Service Studioでサービスを利用する
  3. 最終調整を行う

このドキュメントでは、これらの各タスクについて説明します。

このトピックで説明するタスクのサンプル実装は、OutSystems Forgeで確認することができます。

サービス仕様の取得

この最初の手順では、利用するサービスを特定してサービス仕様をダウンロードします。

以下の手順を実行します。

  1. SAP API Business Hubを開きます。

  2. 検索ボックスでサービスを検索します。
    このガイドで示す例では、SAP S/4HANA Cloudの「Product Master - Create, Read, Update, Delete」サービスを使用します。

  3. サービス名をクリックしてサービスのページに移動し、[Details]タブに移動します。

  4. Download Specification]をクリックして[JSON]オプションを選択します。Service Studioでは、JSON Swaggerの仕様ファイルからのサービスの作成をサポートしています。
    注記: 仕様をダウンロードするには、SAPアカウントへのサインインが必要です。

Service Studioでのサービスの利用

新しいモジュールを作成する

以下のガイドラインに従い、この特別な目的のために作成された個別のモジュールに利用対象のサービスを分離する必要があります。

  • リアクティブWebアプリとモバイルアプリでのみサービスを使用する場合は、「Library」モジュールを作成します。
  • 従来のWebアプリでサービスを使用する必要がある場合は、「Service」モジュールを作成します。

仕様からサービスを作成する

Service Studioで、先ほどダウンロードしたJSON Swagger仕様ファイルを使用してサービスを利用します。

以下の手順を実行します。

  1. モジュールの[Logic]タブで、IntegrationsにあるREST要素(SAP要素ではありません)を右クリックして[Consume REST API...]を選択します。

  2. Add All Methods]オプションを選択します。

  3. Choose a File]をクリックし、先ほどダウンロードした仕様ファイルを選択して[Finish]をクリックします。

    Note: SAPのサービス仕様に複数のデータ型(例: Text、Integer、Null)のアトリビュートが含まれる場合がありますが、これはOutSystemsではサポートされません。この場合、プラットフォームがこれらのアトリビュートで最も許容されるデータ型を想定し、これらの変更に関する警告メッセージを表示します。

    この警告メッセージが表示されたら、メッセージを閉じて次に進んでください。

最終調整の実行

名前にドル記号($)が含まれるパラメータを処理する

OData標準では、レコードのリストを返すGETメソッドの入力パラメータにドル記号($)で始まる予約語が使用されます。該当する入力パラメータを以下に示します。

$select
APIが返すフィールドを定義できます。OutSystemsでは動的な出力ストラクチャがサポートされていないため、大抵の場合、この入力パラメータは削除します。
$orderby
結果セットのソートに使用するフィールドを指定できます。
$filter
OData仕様の「10.2.3.1. The $filter System Query Option」で定義された形式で条件を指定し、結果セットをフィルタリングできます。
$expand
子エンティティを展開できます。
$inlinecount
自動的に生成されるストラクチャでは、このinline countアトリビュートは考慮されません。この入力パラメータは削除できます。
$skip
結果セットの最初の一定数の結果をスキップできます。
$top
結果セットの最大レコード数を定義できます。

エンコードの問題のため、サービスへの送信リクエストにはこれらの入力パラメータの「$」(ドル記号)文字は含まれません。この問題を解決するには、「OnBeforeRequest」ハンドラを使用します。これらのハンドラの詳細については、「シンプルなカスタマイズ」をご覧ください。

「OnBeforeRequest」ハンドラを作成するには、以下の手順を実行します。

  1. Service Studioで、インポートされたサービスに対応するRESTフォルダにあるツリー要素を選択します。

  2. 「On Before Request」プロパティを「New OnBeforeRequest」に設定して、「OnBeforeRequest」ハンドラを利用対象のサービスに追加します。

  3. REST API要素に追加された「OnBeforeRequest」コールバックアクションを開いてフローを定義します。

「OnBeforeRequest」ハンドラで、以下の手順を実行します。

  1. URLクエリパラメータのリストのコピーを作成します。
  2. For Eachを使用して、新しいリストのURLクエリパラメータをすべて順に処理します。
    1. 各要素について、クエリパラメータが予約名(ドル記号を除いたもの)のいずれかに一致するかどうかを確認します。
    2. 一致する場合、名前の最初に「$」(ドル記号)を追加します。

たとえば、「top」という名前のURLクエリパラメータが見つかった場合、その名前の最初に「$」を追加するため、「$top」という名前になります。

実装例を以下に示します。

リクエストに必要なヘッダーを追加する

SAP ODataサービスでは、リクエストごとに2つの追加のヘッダーが必要です。リクエスト本文のコンテンツタイプをJSONとして示すヘッダーと、レスポンスで同じコンテンツタイプを要求するヘッダーです。パラメータ名の「$」文字を処理するために先ほど作成した「OnBeforeRequest」ハンドラにこれらのヘッダーを追加します。

以下の手順を実行します。

  1. 「OnBeforeRequest」ハンドラに「HTTPHeader」データ型のローカル変数を追加します。

    注記: 「HTTPHeader」データ型は、Service StudioでSAPサービスを利用したときにOutSystemsによって作成されたストラクチャです。

  2. Assign要素を使用して、以下の値をローカル変数の「Name」アトリビュートと「Value」アトリビュートに割り当てます。

    <ローカル変数名>.Name = "Accept"
    <ローカル変数名>.Value = "application/json"

  3. ListAppendサーバーアクションを使用して、このHTTPHeaderストラクチャをリクエストのヘッダーリスト(「CustomizedRequest.Headers」リスト)に追加します。

  4. 前の2つの手順を繰り返して、以下の「Name」と「Value」を使用してHTTPヘッダーをもう1つ追加します。同じローカル変数を再利用する必要があります。

    <ローカル変数名>.Name = "Content-Type"
    <ローカル変数名>.Value = "application/json"

2つのヘッダーを追加する実装例を以下に示します。

エラーレスポンスを処理する

通常、SAP ODataサービスの呼び出しでエラーがあった場合、サービスは通常の正常なレスポンスとは異なるストラクチャを使用してレスポンスを返します。このストラクチャを解析するため、OutSystemsの利用対象のサービスに「OnAfterResponse」ハンドラを追加する必要があります。これにより、より適切な例外のスローとロギングを行うことができます。

残念ながら、エラーのストラクチャはエラーの発生レベルによって異なります。このため、このガイドで示す手順を使用して、特定のユースケースで発生する可能性のあるすべてのエラータイプに対応することはできない可能性があります。

以下の手順を実行します。

  1. Service Studioで、インポートされたサービスに対応するRESTフォルダにあるツリー要素を選択します。

  2. 「On After Response」プロパティを「New OnBeforeRequest」に設定して、「OnAfterResponse」ハンドラを利用対象のサービスに追加します。

「OnAfterResponse」ハンドラで以下のロジックを実装する必要があります。

  1. レスポンスにエラーステータスコードが含まれるかどうかを確認します。エラーステータスコードは、200~299以外のステータスコードです。
    1. ステータスコードが「正常」(200~299のステータスコード)を示している場合、必要な処理はありません。ハンドラフローを「End」要素で終了することができます。
    2. ステータスコードが「エラー」を示している場合、受信したエラーのタイプに応じてレスポンスを解析します。
      以下の例では、「Parse_ErrorResponse」という別のアクションで解析を行っています。

実装例を以下に示します。

エラーレスポンスを解析する

レスポンスストラクチャの異なる様々な種類のエラーレスポンスを処理するためのロジックを実装する必要があります。たとえば、少なくとも以下の種類のエラーを処理する必要があります。

  • データエラー:データの取得時、更新時、挿入時のエラー。通常はサービス仕様ファイルで定義されたエラーストラクチャによって返されます。
  • 障害エラー:認証のエラーやその他の予期しないエラー。通常は「fault」要素を含みます。
  • APIエラー:「Service Unavailable」などのエラー。通常はHTTPステータスコードとエラーメッセージを含みます。

ロジックで以下の方法を使用してエラーレスポンスを解析することを推奨します。

  1. データエラーの処理:レスポンステキストからサービス仕様で定義されたエラーストラクチャへの逆シリアル化を試みます。得られるストラクチャにエラーメッセージのテキスト値が含まれる場合、その値を含む例外をスローします。
  2. 障害エラーの処理:障害のサンプルに基づいてこれらのエラーのストラクチャを定義し、「fault」要素のテキストを含む例外をスローします。
  3. APIエラーの処理:APIエラーのサンプルに基づいてこれらのエラーのストラクチャを定義し、「code」要素と「error」要素にテキストがある場合はそれらを含む例外をスローします。

以下のセクションでは、これらの種類のエラーレスポンスの処理の詳細について説明します。

ヒント: Structuresツリー要素を右クリックして[Add Structure from JSON...]オプションを選択すると、JSONのサンプルレスポンスからストラクチャを作成することができます。

1. データエラーを処理する

ほとんどの場合、サービス仕様をインポートすると、OutSystemsによってデータエラーのエラーストラクチャが作成されます。これはデータの取得時、更新時、挿入時にエラーがあった場合にサービスが返すストラクチャです。 エラー処理ロジックでは、最初にエラーレスポンスを解析してこのデータエラーストラクチャへの変換を試みます。

以下の手順を実行します。

  1. Service Studioで、データエラーに使用されるストラクチャを特定します。このストラクチャは、[Data]タブのサービス名の要素ツリーにある[Structures]フォルダにあります。
    この例のエラーストラクチャの名前は「error」です。

  2. エラー解析ロジック(この例では、「Parse_ErrorResponse」アクション)で、レスポンステキストからエラーストラクチャへの逆シリアル化を試みます。

  3. 得られるストラクチャにエラーメッセージのテキスト値が含まれる場合、その値を含む例外をスローします。

実装例を以下に示します。

2. 障害エラーを処理する

認証エラーや予期しないエラーなどの障害エラーでは、エラーレスポンスの形式が異なります。エラーレスポンスがデータエラーではない場合、次にレスポンステキストを解析して障害エラーストラクチャへの変換を試みます。

以下の手順を実行します。

  1. Structuresツリー要素を右クリックして[Add Structure from JSON...]オプションを選択し、障害エラーのサンプルレスポンスからストラクチャを作成します。

    障害レスポンスの例を以下に示します。

    {
        "fault": {
            "faultstring":"Failed to resolve API Key variable request.header.apikey",
            "detail":{
                "errorcode":"steps.oauth.v2.FailedToResolveAPIKey"
            }
        }
    }
    
  2. エラー解析ロジック(この例では、「Parse_ErrorResponse」アクション)に、レスポンステキストを解析して障害エラーストラクチャに変換するロジックを追加します。

  3. ストラクチャで「faultstring」値が定義されている場合、この要素のテキストを含む例外をスローします。

実装例を以下に示します。

3. APIエラーを処理する

これはエラーロジックで処理する必要がある3種類目のエラーです。APIエラーは、サービスが利用できないときなどに発生します。この場合、HTTPステータスコードとエラーメッセージを含むレスポンスを受け取ります。

以下の手順を実行します。

  1. Structuresツリー要素を右クリックして[Add Structure from JSON...]オプションを選択し、APIエラーのサンプルレスポンスからストラクチャを作成します。

    APIエラーの例を以下に示します。

    {
        "code":"503",
        "message":"Service is temporarily unavailable for maintenance."
    }
    
  2. エラー解析ロジック(この例では、「Parse_ErrorResponse」アクション)に、レスポンステキストを解析してAPIエラーストラクチャに変換するロジックを追加します。

  3. ストラクチャで「message」値が定義されている場合、この要素のテキストを含む例外をスローします。

実装例を以下に示します。

  • Was this article helpful?