MethodInstance

[アーティクル]
06/15/2015

MethodInstance オブジェクトは、特定の既定値のセットを使用するメソッドの使用方法と、ビジネスデータカタログのセマンティクスであるメソッドインスタンスの種類を説明します。MethodInstance オブジェクトは、メソッドへの参照にパラメータの既定値を加えたものです。Method オブジェクトが実行できないのに対して、MethodInstance オブジェクトは実行できます。各 MethodInstance オブジェクトがメソッド署名と一連の既定値の組み合わせである場合、1 つのメソッドに複数のメソッドインスタンスを持つことができます。メソッドインスタンスを使用して、同じメソッドに異なる既定値を使用して実行できます。

複雑な Web サービスではメソッドインスタンスが特に便利です。メソッドが複数の構造やネストした複雑な構造を返す場合、MethodInstance メタデータはクライアントに返す構造や構造の一部を指定することができます。MethodInstance オブジェクトを完全に定義するには、必要に応じて XML の return parameter に従って TypeDescriptor 要素を定義できます。以下に例を示します。

<MethodInstance Name="bla" Type="Finder" ReturnParameterName="foo" ReturnTypeDescriptorName="baz" ReturnTypeDescriptorLevel="5">

ReturnTypeDescriptorName 属性は省略できます。この属性が指定されていない場合、ビジネスデータカタログでは Return パラメータ要素のルートの TypeDescriptor を前提とします。ReturnTypeDescriptorLevel 属性も省略できます。この属性が指定されず同様に指定された型記述子が複数存在する場合、例外がスローされます。同じレベルに同様に指定された型記述子が複数存在する場合 (このような状況はまれである)、最初のものが前提とされます。これにより WebMethod オブジェクトが複数の方法で再利用できるため、この柔軟性は重要です。Customers のコレクションを返す WebMethod と、各カスタマがアドレスのコレクションを含む場合を考えてみてください。この WebMethod を使用するビジネスデータカタログの MethodInstance オブジェクトは、Customer の Finder、Customer の SpecificFinder、CustomerToAddress Association (Customer のアドレスを返す) の 3 つです。MethodInstance モデルでは、ユーザーに Return パラメータ内の TypeDescriptor を指定させることにより、メタデータの作成者は関連性のある Return パラメータの部分のみを定義する必要があります。

Associations は MethodInstance クラスの派生クラスであり、Association の定義形式も必要に応じて ReturnTypeDescriptor の値をとります。

<Association Name="CustomerToAddresses" AssociationMethodEntityName="Customer" AssociationMethodName="GetCustomerByID" AssociationMethodReturnParameterName="Customer" AssociationMethodReturnTypeDescriptorName="CustomerAddresses" AssociationMethodReturnTypeDescriptorLevel="1">
      <SourceEntity Name="Customer" />
      <DestinationEntity Name="Address" />
    </Association>

最後に、MethodInstance のオブジェクトモデルは ReturnTypeDescriptor のアクセサまたはプロパティも提供します。ReturnParameter は暗黙的に ReturnTypeDescriptor の一部であり、このオブジェクトモデルはオブジェクト参照を使用して動作するため、オブジェクトモデルの使用時には ReturnParameter を指定する必要はありません。

一部のメソッドインスタンスには、汎用クライアントを有効にするという特殊な用途があります。

Finders と SpecificFinders

Finder はエンティティのインスタンスを返す特別なメソッドです。SpecificFinder は厳密に 1 つのエンティティのインスタンスを返します。Finder メソッドは静的なメソッドで、入力パラメータとしてのキーを取得しません。SpecificFinder メソッドも静的なメソッドですが、明示的にキー (ID) を取得します。

関連付けによってのみ到達可能なエンティティは検索機能を持ちません。その他のエンティティは、複数のインスタンスを返す 1 つの Finder メソッドと、指定された ID の 1 つのインスタンスを返す 1 つの SpecificFinder メソッドを持つ必要があります。

たとえば Customer エンティティの場合、Finder メソッドは SELECT * FROM Customers であり、SpecificFinder メソッドは SELECT * FROM Customers WHERE CustomerID = id であると考えられます。

エンティティに Finder メソッドを定義しない場合、そのエンティティはビジネスデータリスト Web パーツで使用できません。SpecificFinder メソッドを定義しない場合、そのエンティティではアクションの設定、検索やインデックス付け、および関連リスト Web パーツ以外のビジネスデータ機能での使用は行えません。

Finder を評価するには、対応するメソッドが入力としてフィルタ可能なパラメータをとり、レコードのコレクションを返す必要があります。ここで各レコードは、それぞれが表すエンティティインスタンスのキーを含む必要があります。SpecificFinder として評価するには、対応するメソッドが入力パラメータの 1 つとしてエンティティインスタンスのキーをとる必要があり、そのフィールドの 1 つがキーであるフィールドを返す必要があります。

以下にフィルタ可能なパラメータを持つ Finder メソッドのもう少し複雑な例を示します。

SELECT ProductID, Name, ProductNumber, ListPrice FROM Product WHERE (ProductID &gt;= @MinProductID) AND (ProductID &lt;= @MaxProductID) AND (Name LIKE @Name) AND ProductNumber LIKE @ProductNumber)

Finder メソッドと SpecificFinder メソッドは、同じフィールドを返す必要はありません。SpecificFinder メソッドが Finder メソッドよりも多くのフィールドを返すシナリオがあるとします。ただし、双方ともエンティティで定義された ID を返す必要があります。

Finder メソッドと SpecificFinder メソッドは、厳密に対応する 1 つのメソッドインスタンスを持つ必要があります。

SpecificFinder メソッドは、エンタープライズ検索とインデックス付けにおいて重要な役割を実行します。ビジネスデータカタログのクロールには次の 2 つのフェーズがあります。

ID 列挙 : すべてのエンティティインスタンス ID をフェッチします。
詳細フェッチ : 各エンティティインスタンスの詳細をフェッチします。

IDEnumerator (このトピックの後で説明) は ID を返し、SpecificFinder メソッドは各エンティティインスタンスの詳細を返します。

ViewAccessor

view は、エンティティのフィールドのコレクションです。エンティティの view には Finder、SpecificFinder など、MethodInstance オブジェクトのいずれかによって返されるフィールドが含まれます。ViewAccessor は、既定以外のビュー、つまり、ビジネスアプリケーションからの異なるフィールドのセットを返す特別な別のメソッドです。ViewAccessor メソッドは、暗黙的にキー (ID) を取得するインスタンスメソッドです。つまり、キーを指定する必要はありません。ビジネスデータカタログが自動的にキーを提供します。

エンティティが持つ ViewAccessor メソッドの数は、ゼロまたは複数です。

注意

エンタープライズ検索ではエンティティの SpecificFinder ビューのみをクロールします。

Finder および SpecificFinder メソッドはメソッドインスタンスを 1 つしか持つことができませんが、ViewAccessor メソッドは 1 つ以上のメソッドインスタンスを持つことができます。こうした柔軟性は、同一メソッドが複数の構造を返し、それぞれがビューを構成する場合に便利です。SAP のようなシステムには、関連フィールドの複数のコレクションをユーザーに返す API (BAPI_CUSTOMER_GETDETAIL2 など) があります。たとえば Customer の GetDetails API は、財務データを含む構造やアドレスデータを含む構造などを返します。

注意

ビジネスデータ Web パーツ、リストなど、ビジネスデータ機能はエンティティビューをサポートしています。

IDEnumerator

ビジネスデータカタログのクロールには次の 2 つのフェーズがあります。

ID 列挙 : すべてのエンティティインスタンス ID をフェッチします。
詳細フェッチ : 各エンティティインスタンスの詳細をフェッチします。

IDEnumerator メソッドは検索可能な各エンティティの ID (一意のキー) のリストを返し、SpecificFinder メソッドは各エンティティインスタンスの詳細を返します。これにより IDEnumerator メソッドが返す ID を持つエンティティのインデックス付けが可能になります。

注意

増分クロールが必要な場合は、エンティティの IdEnumerator の戻り値のフィールドの 1 つが、基幹業務 (LOB) アプリケーションでエンティティインスタンス (またはデータベース用語では行) が最後に更新された時刻を表すことを確認する必要があります。その後で、最終更新日を表す IDEnumerator の戻り値にある TypeDescriptor の名前を持つエンティティの __BdcLastModifiedTimestamp プロパティを設定する必要があります。

エンティティが持つ IDEnumerator メソッドの数は、ゼロまたは 1 つです。IDEnumerator メソッドが返す ID のリストに制限はありません。戻り値パラメータで他のフィールドを返す場合、ビジネスデータカタログはクロール時にこれを無視します。

LastIdSeen フィルタを使用すると IDEnumerator メソッドのチャンクが有効になります。Web サービスやその他のストリーミングを行わないバックエンドアプリケーションでパフォーマンスを改善するには、以下のように IDEnumerator メソッドで LastIdSeen フィルタを使用します。

SELECT TOP 100 Id FROM Customers WHERE Id>=@LastIdSeen
ORDER BY Id

AccessChecker

AccessChecker は 1 つ以上のエンティティインスタンスでユーザーが持っている権限を返すメソッドです。権限は、単一のビットまたはビットの集まりです。権限を一度決定すると、Entity.CheckAccess メソッド経由でビジネスデータクライアントアプリケーションから権限を使用できます。たとえば、ユーザーが EntityInstance の Create、Edit、Delete アクションを表示するビジネスデータカタログにユーザー定義の Web パーツを構築する場合を考えてみます。ここで AccessChecker を定義することにより、ユーザーは Entity.CheckAccess を呼び出して、返される権限によって 1 つ以上のアクションを条件付きで有効にできます。AccessChecker の例については、「AccessChecker サンプル」を参照してください。

エンティティが持つ AccessChecker メソッドの数は、ゼロまたはエンティティにつき 1 つです。

GenericInvoker

GenericInvoker は、前に説明したメソッドには含まれないバックエンドの LOB アプリケーションで起動できるメソッドです。たとえば、GenericInvoker メソッドを使用して、エンティティを編集したり Products テーブルの単価を更新したりするバックエンドアプリケーションのメソッドを実行できます。

エンティティが持つ GenericInvoker の数は、ゼロまたは複数です。

ビジネスデータカタログは認証、承認、およびその他のセキュリティ要件を管理するため、バックエンドシステムのロジックを起動する必要があるユーザー定義の Web パーツを作成する場合に GenericInvoker メソッドは非常に便利です。

注意

ビジネスデータ Web パーツ、リストなど、ビジネスデータ機能では、GenericInvoker メソッドを使用しません。ただし、オブジェクトモデルと XML スキーマではこの種類のメソッドインスタンスをサポートしています。

Scalar

Scalar はバックエンドの LOB アプリケーションで起動可能な 1 つの値を返すメソッドです。たとえば Scalar メソッドを使用して、バックエンドのアプリケーションから今までの売り上げ合計を取得できます。

エンティティが持つ Scalar メソッドの数は、ゼロ以上です。

例

<MethodInstances>
            <MethodInstance Type="SpecificFinder" ReturnParameterName="LineItem" ReturnTypeDescriptorName="LineItem" ReturnTypeDescriptorLevel="0" Name="FindLineItemInstance" />
</MethodInstances>

スキーマ

子	型	出現回数	制限/使用する値	説明
Type	属性 (bdc:MethodInstanceType)	1..1	Finder SpecificFinder ViewAccessor GenericInvoker IdEnumerator Scalar AccessChecker	Finder: フィルタ条件を指定した一連のエンティティインスタンスを返すメソッド。 SpecificFinder: 一連の識別子を指定した 1 つのエンティティインスタンスを返すメソッド。 ViewAccessor: エンティティインスタンスを指定した新しいビュー (フィールドのセット) を返すメソッド。 IdEnumerator: エンティティインスタンスの識別子を返すメソッド。2 段階のビジネスデータカタログ検索プロトコルで使用されます。最初にエンティティオブジェクトの IdEnumerator が呼び出され、その後で詳細を取得する各インスタンスの FindSpecific が呼び出されます。 GenericInvoker: いずれかのメソッド
ReturnParameterName	属性 (String)	1..1		この MethodInstance が実行されるときにビジネスデータカタログが戻り値パラメータとして扱うメソッドの Parameter の名前。
ReturnTypeDescriptorName	属性 (String)	0..1		この MethodInstance が実行されるときにビジネスデータカタログが戻り値の構造として扱う戻り値パラメータの TypeDescriptor の名前。ReturnTypeDescriptorName 属性は省略できます。この属性が指定されていない場合、ビジネスデータカタログは ReturnParameter のルートの TypeDescriptor を前提とします。
ReturnTypeDescriptorLevel	属性 (Int32)	0..1		戻り値のパラメータの ReturnTypeDescriptor のレベル。ReturnTypeDescriptorLevel 属性は省略できます。この属性が指定されず、同様に指定された TypeDescriptor が複数存在する場合は、例外がスローされます。同じレベルに同様に指定された TypeDescriptor が複数存在する場合は、最初のものが前提となります。

Share via