組織サービスを使用する基本的な操作

10 分

このユニットでは、Dataverse 環境からのデータの操作を行う組織サービスを使用する基本的な操作について詳しく説明します。

行の作成

行を作成するには、Create メソッドを使用します。必須ではない場合、テーブルのプライマリ列に対して少なくとも値を 1 つ指定してください。 Create 操作により、新しい行に対して、GUID 値が主キーとして割り当てられます。独自の値の入力がサポートされている場合、ほとんどのシナリオで自動割り当てを許可することをお勧めします。

    Entity newAccount = new Entity("account");
    newAccount["name"] = "Contoso";
    Guid accountid = serviceClient.Create(newAccount);

エンティティオブジェクトで RelatedEntities プロパティを使用し、同じ操作で関連行を作成することもできます。これを行うには、同時に作成する必要があるリレーションシップ名と関連エンティティオブジェクトを指定する必要があります。次の例では、指定された関係を使用して、アカウントと連絡先の両方の行が 1 つのトランザクションで作成され、まとめて関連付けられています。

Entity newAccount = new Entity("account");
newAccount["name"] = "Contoso";

Entity newContact = new Entity("contact");
newContact["firstname"] = "Jim";
newContact["lastname"] = "S";

newAccount.RelatedEntities.Add(new Relationship("account_primary_contact"),
    new EntityCollection(new List<Entity>() { newContact }));

Guid accountid = serviceClient.Create(newAccount);

行の更新

行を更新するには、Update メソッドを使用します。テーブル行は、主キーまたは代替キーを使用して更新することができます。行を更新する場合、データを変更する列のみを指定する必要があります。エンティティオブジェクトに変更されていない列が含まれている場合、値が変更されていなくても、それらの列の変更のため、オートメーションの待機が Dataverse によりトリガされます。次に、主キーである GUID を使用した更新の例を示します。

Entity updateAccount = new Entity("account",accountid);
updateAccount["accountnumber"] ="ABC123";
updateAccount["creditlimit"] = new Money(1000);

serviceClient.Update(updateAccount);

代替キーを使用してテーブル行を更新することもできます。これを機能させる前に、テーブルで代替キーを定義する必要があります。次の例では、前の更新操作で設定した取引先企業番号を使用して、アカウントテーブル行を更新しています。

Entity updateAccount = new Entity("account","accountnumber", "ABC123");
updateAccount["creditlimit"] = new Money(2300);
serviceClient.Update(updateAccount);

KeyAttributeCollection を使用して、代替キーを構成する複数の列を提供することもできます。

KeyAttributeCollection updateKeys = new KeyAttributeCollection
{
    { "name", "Contoso" },
    { "accountnumber", "Contoso123A" }
};
Entity updateAccount = new Entity("account", updateKeys);
updateAccount["creditlimit"] = new Money(5000);

serviceClient.Update(updateAccount);

行の削除

行を削除するには、Delete メソッドを使用します。テーブル行は、主キーまたは代替キーを使用して削除することができます。次のコードは、主キーを使用して行われる最も基本的な削除操作を示しています。

serviceClient.Delete("account", accountid);

代替キーによって削除する場合、Execute メソッドを持つ DeleteRequest メッセージを使用する必要があります。次のコードは、特定の取引先企業番号列の代替キーを含むアカウント行の削除を示します。

var deleteRequest = new DeleteRequest
{
    Target = new EntityReference("account", "accountnumber", "Contoso123A")
};

serviceClient.Execute(deleteRequest);

1 つの行を取得する

1 つの行を取得するには、Retrieve メソッドを使用します。テーブル行は、主キーまたは代替キーを使用して取得することができます。次のコードサンプルは、主キーを使用して行われる最も基本的な取得操作を示しています。

var retrieveAccount = serviceClient.Retrieve("account", accountid,
    new ColumnSet("name", "accountnumber", "creditlimit"));

代替キーによって取得する場合、Execute メソッドを持つ RetrieveRequest メッセージを使用する必要があります。次のコードサンプルは、特定の取引先企業番号列の代替キーを含むアカウント行を 1 つ取得する操作を示しています。

var altRetrieveKey = new EntityReference("account", "accountnumber",accountNumber);
var retrieveRequest = new RetrieveRequest
{
    Target = altRetrieveKey,
    ColumnSet = new ColumnSet("name", "accountnumber", "creditlimit")
};
var retrieveResult = (RetrieveResponse)serviceClient.Execute(retrieveRequest);

複数行を取得する

条件に一致するテーブルから複数行を取得するには、RetrieveMultiple メソッドを使用します。 Dataverse の単一または複数のテーブルの行に対するクエリ基準を作成する方法には複数のオプションがあります。各オプションには、クエリのシナリオによって異なる利点があります。 RetrieveMultiple メソッドで使用できる主要なオプションは次のとおりです。

QueryExpression: 複雑なクエリを作成するための、厳密に型指定されたオブジェクトモデルで、リンクされた (関連する) 行からのデータが含まれますが、集計およびグループ化はサポートされていません。
QueryByAttribute: QueryExpression より単純なモデルで、1 つのテーブルの列の値の基準を照合する場合に便利ですが、返すのは 1 つのテーブルからのデータのみです。
FetchExpression - Dataverse の FetchXML クエリ言語を使用し、リンクされた (関連する) テーブル行からの集計、グループ化、データ包含を含む複雑なクエリを実現します。
LINQ: LINQ 構文を使用してクエリを作成しますが、機能は QueryExpression と同じものに限定されます。

次の例では、同じ基準を各オプションで示しています。この基準は、"City" が "Redmond" である取引先企業テーブルを照会し、"address1" の "City" 列および "Line 1/2" 列を返します。

QueryExpression の例

var queryExpression = new QueryExpression("account")
{
    ColumnSet = new ColumnSet("address1_city", "address1_line1", "address1_line2"),
    Criteria = new FilterExpression
    {
        Conditions =
        {
            new ConditionExpression("address1_city", ConditionOperator.Equal, "Redmond")
        }
    }
};
EntityCollection queryExpressionResults = serviceClient.RetrieveMultiple(queryExpression);

QueryByAttribute の例

var queryByAttribute = new QueryByAttribute("account")
{
    ColumnSet = new ColumnSet("address1_city", "address1_line1", "address1_line2"),
    Attributes = { "address1_city" },
    Values = { "Redmond" }
};
EntityCollection queryByAttributeResults = serviceClient.RetrieveMultiple(queryByAttribute);

FetchExpression の例

var fetchXml = @"
<fetch version='1.0' output-format='xml-platform' mapping='logical' distinct='false'>
  <entity name='account'>
    <attribute name='address1_city' />
    <attribute name='address1_line1' />
    <attribute name='address1_line2' />
    <filter type='and'>
      <condition attribute='address1_city' operator='eq' value='Redmond' />
    </filter>
  </entity>
</fetch>";

var fetchExpression = new FetchExpression(fetchXml);
EntityCollection fetchResults = serviceClient.RetrieveMultiple(fetchExpression);

LINQ の例

var context = new OrganizationServiceContext(serviceClient);

var linqQuery = from acc in context.CreateQuery("account")
                where (string)acc["address1_city"] == "Redmond"
                select new
                {
                    Address1_City = (string)acc["address1_city"],
                    Address1_Line1 = (string)acc["address1_line1"],
                    Address1_Line2 = (string)acc["address1_line2"]
                };

var linqResults = linqQuery.ToList();

続行