プラグインの標準API接続

リリース26A以降、Oracle Fusion Field Serviceは、プラグインが他のFusion製品およびOracle Fusion Field Service APIのREST APIにアクセスするためのプロセスを標準化しました。 この更新により、以前はFusionおよびOracle Fusion Field Service REST APIのアプリケーション・エンドポイントおよびAPIアクセス・レベルの設定に必要だった、Oracle Fusion Field Serviceのアプリケーション機能への以前の依存がなくなります。

ノート: これらの改善は、Oracle Fusion Field Serviceユーザーに有効です。 APIコールのレガシー・アプリケーション・メソッドは、Oracle Field Serviceユーザーに対して引き続き使用可能で、サポートされます。

プラグインAPIの変更点

プラグインAPIを使用した環境名およびREST API URLの取得

プラグインは、すべてのライフサイクル・ステージで必要な環境名とREST API URLを簡単に取得できるようになりました。 init、open、updateResult、および wakeupメソッドに、次のパラメータを持つ環境オブジェクトが含まれるようになりました。

  • environmentName: プラグインのアクセス・レベルを定義するスコープの作成に必要です。
  • fsUrl - Oracle Field Service RESTサーバーURL
  • faUrl - Oracle Fusion Services RESTサーバーURL

例

{
    "apiVersion": 1,
    "method": "init" / "open" / "updateResult" /"wakeup",
    ...
    "environment": {       
        "environmentName": "xxxxxxxxx",
        "fsUrl": "https://xxxxxxxxx.fs.ocs.oraclecloud.com",
        "faUrl": "https://xxxxxxxxx.fa.ocs.oraclecloud.com"
    }
}

IDCSを使用したOracle Field ServiceおよびFusion REST APIへのアクセス

Fusionエコシステム全体のREST APIへのアクセスは、Fusion環境にプロビジョニングされたIDCS (Identity Cloud Service)を介して標準化されます。 IDCSのOracleクラウド・サービス・セクションにあるフィールド・サービス・アプリケーションは、Oracle Fusion Field Service APIおよびその他のFusion製品APIを含むすべての必須APIへのアクセス権を付与します。

アイデンティティとセキュリティ

アイデンティティとセキュリティ

プラグインを実装する場合、インテグレータは、目的のAPIコールを行う前に、IDCSからターゲットAPIのアクセス・トークンを取得するロジックを含める必要があります。

REST APIに対して認証するためのアクセス・トークンの取得

  • 新しいgetAccessTokenByScopeプロシージャ: 新しいプラグインAPIプロシージャgetAccessTokenByScopeを使用して、REST API認証に必要なアクセス・トークンを取得します。
  • トークンを取得するためのユーザー・アサーション・フロー: トークンはユーザー・アサーション・フローを使用して発行されます。つまり、トークンは現在のプラグイン・ユーザーに関連付けられます。 このトークンを使用してプラグインを使用して行われたすべての変更は、そのユーザー名でターゲット・アプリケーションに記録されます。
  • アクセス・トークンの有効期限: OAuthアクセス・トークンは、3600秒(1時間)後に失効します。


アクセス・トークンを取得するリクエストで'scope'パラメータを渡す
scopeパラメータは、新しいgetAccessTokenByScopeプロシージャをコールするときに必須です。 これは、特定の要求へのREST APIアクセスを制限するために使用される重要なセキュリティ・パラメータであり、ユーザーが定義済リソースの外部のデータにアクセスできないようにします。 パラメータのタイプはStringです。

ノート: REST APIコールのターゲット環境を正しく識別するには、scopeパラメータ内に環境名を含める必要があります。

Oracle Fusion Field Service APIのオーディエンスとスコープ

アプリケーションでは、次のプライマリ・オーディエンスと5つの異なるスコープが定義されます。

プライマリ・オーディエンス: urn:opc:resource:fusion:xxxxxxxxx:field-service-common:

スコープ

スコープ 説明
/ - デフォルト・スコープ。 アクセスを許可: Swagger/openapiエンドポイント
/使用 モバイル就業者プランニング。 次を含む: アクティビティ読取り/書込み、リソース読取り/書込み、インベントリ読取り/書込み、容量読取り専用、メタデータ読取り専用
/ビュー 読取り専用アクセス: /useスコープと同じですが、すべてのアクセスは読取り専用に制限されます。
イベント イベントの受信: イベントAPIへのアクセス権を付与します。
設定 管理: メタデータ、統計および部品カタログへの読取り/書込みアクセス権を付与します。

Fusion APIのスコープ

IDCSが提供するOracle Fusion Field Serviceアプリケーションは、'Fusion Applications Cloud Service'リソースに接続され、スコープ'urn:opc:resource:faaas:fa:XXXXXXXXXurn:opc:resource:consumer::all'によってFusion REST APIにアクセスできます。

IDCS内のOracle Fusion Field Serviceアプリケーションは、Fusion Applications Cloud Serviceリソースに接続されます。 この接続は、次のスコープを使用してFusion REST APIへのアクセス権を付与します:

urn:opc:resource:faaas:fa:XXXXXXXXXurn:opc:resource:consumer::all


ノート: プラグインを開発する場合、システム・インテグレータは、プラグイン・コード内のターゲットAPIごとに適切なスコープを明示的に定義する必要があります。 このスコープは、JWTアクセス・トークンを取得するためにIDCSへのリクエストで使用されます。


「getAccessTokenByScope」プロシージャの例

リクエスト

{
    "apiVersion": 1,
    "method": "callProcedure",
    "callId": "1111111111",
    "procedure": "getAccessTokenByScope",
    "params": {       
        "scope": "urn:opc:resource:faaas:fa:XXXXXXXXXurn:opc:resource:consumer::all"
    }
}

レスポンス

{
    "apiVersion": 1,
    "method": "callProcedureResult",
    "callId": "1111111111",
    "procedure": "getAccessTokenByScope"
    "resultData": {
        "token": "...",
        "status": "success",
        "detail": ""
    }
}

エラー

エラーの例

{
    "apiVersion": 1,
    "method": "error",
    "callId": "...",
    "errors": [
        {
            "type": "TYPE_PROCEDURE_GET_ACCESS_TOKEN_NATIVE_ERROR",
            "code": "CODE_GET_ACCESS_TOKEN_NATIVE_OFFLINE_NOT_SUPPORTED",
            "procedure": "getAccessTokenByScope"
        }
    ]
}
{
    "apiVersion": 1,
    "method": "error",
    "callId": "...",
    "errors": [
        {
            "type": "TYPE_PROCEDURE_GET_ACCESS_TOKEN_NATIVE_ERROR",
            "code": "CODE_GET_ACCESS_TOKEN_NATIVE_PROCEDURE_TIMEOUT",
            "procedure": "getAccessTokenByScope"
        }
    ]
}

エラーの完全なリスト

エラー・タイプ エラー・コード 追加のフィールド 根本原因
TYPE_INTERNAL CODE_UNKNOWN
CODE_JSON_INVALID
CODE_METHOD_NOT_SUPPORTED		 - 一般的なエラー検証
TYPE_PROCEDURE_ERROR CODE_PROCEDURE_UNKNOWN procedure 間違ったプロシージャ名
TYPE_PROCEDURE_PARAM CODE_PROCEDURE_PARAM_VALUE_INVALID スコープ パラメータ・スコープが文字列ではありません。 値がnull/空であるか、数値、ブール、オブジェクト、配列型があります。
TYPE_PROCEDURE_GET_ACCESS_TOKEN_ERROR CODE_GET_ACCESS_TOKEN_OFFLINE_NOT_SUPPORTED スコープ デバイスがオフラインのときにgetAccessTokenプロシージャがコールされます。
TYPE_PROCEDURE_GET_ACCESS_TOKEN_ERROR CODE_GET_ACCESS_TOKEN_PROCEDURE_TIMEOUT スコープ プロシージャは15秒以内にサーバーからアクセス・トークンを取得できませんでした。

「アセット詳細」および「報告」の変更
ページの「アプリケーション」を構成する必要性がなくなり、ページはすぐに使用できる他のアプリケーションとネイティブに通信します。
「Applications for REST APIs」セクションが「Asset details」と「Debriefing」の構成から削除されました。

ページは即時利用可能な他のアプリケーションとネイティブに通信するようになり、アプリケーションを構成する必要がなくなります。 その結果、「REST APIのアプリケーション」セクションが、「アセット詳細」および「報告」の構成から削除されました。

ビジネス上の利点

  • 「アセット詳細」および「報告」ページの構成は最小限で済むようになり、すぐに使用できます。
  • カスタム・プラグインでは、Oracle Fusion Field Serviceやその他のFusion製品内でAPIを呼び出すための標準化されたアプローチを利用するようになり、統合と開発が簡素化されました。

有効化および構成ステップ

この機能を有効化するうえで必要な操作はありません。

ヒントと考慮事項

「資産詳細」および「報告」にアプリケーションは不要になりました
画面が他のシステムとネイティブに通信するようになったため、画面のアプリケーションを構成するという要件は削除されました。 「REST APIのアプリケーション」構成セクションは、「アセット詳細」および「報告」に表示されなくなりました。

異なるオーディエンスとスコープを混在させないでください

異なるオーディエンス(監査値)に属するスコープを1つのトークン・リクエスト内で結合することはできません。 Oracle IDCSでは、スコープはこの構造に従います。

urn:opc:resource:<aud>:<resource>:<scope>

  • aud (オーディエンス): トークンの対象となるサービスを定義します(たとえば、Fusion、fa、faas、hcmなど)。
  • scope: サービス内のアクセスを定義します。

異なる監査値を持つスコープをリクエストした場合、IDCSオーディエンスは結果のアクセス・トークンの<aud>クレームに設定し、リクエストは失敗します。

Fusion Services REST Service URLが使用可能な場合
faUrl (Fusion Services REST Server URL)パラメータは、Oracle Fusion Field Service環境内でのみ使用できます。

APIコールへのパスの構築方法
アクセス・トークンを取得すると、システム・インテグレータは、必要なREST APIへのフルパスを構築するためのロジックを実装する必要があります。 init、open、updateResultおよびwakeupプラグインAPIメソッドで使用可能な、環境オブジェクトで提供されるパラメータを使用する最も簡単な方法です。 次のものが含まれます。

  • environmentName - 現在の環境の名前
  • fsUrl - フィールド・サービスRESTサーバーURL
  • faUrl - Fusion Services RESTサーバーURL

REST APIへのフルパスを構築するには、システム・インテグレータが環境名 + RESTサーバーURL + 目的のREST APIへのパスを組み合せる必要があります。 例を次に示します。

  • https://xxxxxxxxx.fs.ocs.oraclecloud.com/rest/ofscMetadata/v1/activityTypes
  • https://xxxxxxxxx.fa.ocs.oraclecloud.com/hcmRestApi/scim/Users