Web APIを使用する FetchXML

  • [アーティクル]

FetchXML Web APIと .NET SDKを使用してデータを取得および集計できる独自のクエリ言語です。 詳細情報: を使用して FetchXML データを照会します。

注意

OData構文を使用するクエリとは異なり、 FetchXML クエリは値を持つプロパティを返しません null 。

特定のテーブルに対してクエリを作成できます。 FetchXML 次に、XML を URL エンコードし、fetchXml クエリ文字列パラメータを使用してエンティティ セットに渡します。

たとえば、次の FetchXML は account エンティティとして存在します。

<fetch mapping='logical'>
   <entity name='account'>
      <attribute name='accountid'/>
      <attribute name='name'/>
      <attribute name='accountnumber'/>      
</entity>
</fetch>

この FetchXML には、次のURLエンコードされた値が含まれます。

%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E

ほとんどのプログラミング言語には、文字列を URL エンコードする関数が含まれています。

RESTful Web サービスに送信する要求を URL エンコードする必要があります。 URL をブラウザーのアドレス バーに貼り付ける場合、ブラウザーはそのアドレスを自動的に URL エンコードする必要があります。

次の例は、 GET 前の FetchXML を使用した、 accounts エンティティ セット パスを使用したリクエストを示しています。 パラメータを使用して、エンコードされた XML を渡します: ?fetchXml=

要求:

GET [Organization URI]/api/data/v9.2/accounts?fetchXml=%3Cfetch%20mapping%3D%27logical%27%3E%3Centity%20name%3D%27account%27%3E%3Cattribute%20name%3D%27accountid%27%2F%3E%3Cattribute%20name%3D%27name%27%2F%3E%3Cattribute%20name%3D%27accountnumber%27%2F%3E%3C%2Fentity%3E%3C%2Ffetch%3E HTTP/1.1
Accept: application/json
OData-MaxVersion: 4.0
OData-Version: 4.0

応答:

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{  
  "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(accountid,name)","value":[  
    {  
        "@odata.etag":"W/\"506678\"",
        "accountid":"89390c24-9c72-e511-80d4-00155d2a68d1",
        "name":"Fourth Coffee (sample)", 
        "accountnumber":"1234",
    },{  
        "@odata.etag":"W/\"502172\"",
        "accountid":"8b390c24-9c72-e511-80d4-00155d2a68d1",
        "name":"Litware, Inc. (sample)"  
    },{  
        "@odata.etag":"W/\"502174\"",
        "accountid":"8d390c24-9c72-e511-80d4-00155d2a68d1",
        "name":"Adventure Works (sample)"  
    },{  
        "@odata.etag":"W/\"506705\"",
        "accountid":"8f390c24-9c72-e511-80d4-00155d2a68d1",
        "name":"Fabrikam, Inc. (sample)"  
    }
  ]  
}

null値を持つプロパティは、 FetchXML を使用して返される結果には含まれないことに注意してください。 例では、返された最初のレコードのみに accountnumber 値があります。

ページング FetchXML

FetchXML を使用すると、 page 要素の count 属性と fetch 属性を設定することで、単純なページングを適用できます。 たとえば、以下の fetchXML はアカウントをクエリし、エンティティ数を 2 に制限し、最初のページだけを返します。

<fetch mapping="logical"
   page="1"
   count="2">
   <entity name="account">
      <attribute name="accountid" />
      <attribute name="name" />
      <attribute name="industrycode" />
      <order attribute="name" />
   </entity>
</fetch>

大量の結果セットのページング

ページング制限が 5,000 に達する大規模な結果セットを扱う場合は、パフォーマンスの向上に役立つクエリでページング クッキーを使用します。 注釈としてページング クッキーを要求します。 prefer: odata.include-annotations 要求ヘッダーで Microsoft.Dynamics.CRM.fetchxmlpagingcookie を使用または含み、@Microsoft.Dynamics.CRM.fetchxmlpagingcookie 注釈は結果で返されます。

次の一連の FetchXML リクエストは、ページング クッキーの使用を示しています。 この例では、小さな count 簡潔にするために値 (3) を使用します。 通常、このような小さいページ サイズにはページング クッキーを使用しません。

<fetch page='1'
   count='3'
   paging-cookie=''
   mapping='logical'
   output-format='xml-platform'
   version='1.0'
   distinct='false'>
   <entity name ='contact'>
      <attribute name ='fullname' />
      <attribute name ='jobtitle' />
      <attribute name ='annualincome' />
      <order descending ='true'
         attribute='fullname' />
      <filter type ='and'>
         <condition value ='%(sample)%'
            attribute='fullname'
            operator='like' />
         <condition value ='18717e9c-643f-ed11-9db0-002248225e95'
            attribute='parentcustomerid'
            operator='eq' />
      </filter>
   </entity>
</fetch>

最初のページ

page を '1' に設定して最初のページを送信します。 Prefer: odata.include-annotations="*" 要求ヘッダーを使用して、応答内の必要な注釈が確実に返されるようにします。

要求:

GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%221%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
  "@odata.count": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcount": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
  "@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
  "@Microsoft.Dynamics.CRM.fetchxmlpagingcookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25221%2522%253e%253cfullname%2520last%253d%2522Robert%2520Lyon%2520%2528sample%2529%2522%2520first%253d%2522Susanna%2520Stubberod%2520%2528sample%2529%2522%2520%252f%253e%253ccontactid%2520last%253d%2522%257b30717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520first%253d%2522%257b20717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />",
  "@Microsoft.Dynamics.CRM.morerecords": true,
  "value": [
    {
      "@odata.etag": "W/\"74359676\"",
      "fullname": "Susanna Stubberod (sample)",
      "jobtitle": "Senior Purchaser",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$52,000.00",
      "annualincome": 52000.0,
      "contactid": "20717e9c-643f-ed11-9db0-002248225e95"
    },
    {
      "@odata.etag": "W/\"74359706\"",
      "fullname": "Scott Konersmann (sample)",
      "jobtitle": "Accounts Manager",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$38,000.00",
      "annualincome": 38000.0,
      "contactid": "2c717e9c-643f-ed11-9db0-002248225e95"
    },
    {
      "@odata.etag": "W/\"74359716\"",
      "fullname": "Robert Lyon (sample)",
      "jobtitle": "Senior Technician",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$78,000.00",
      "annualincome": 78000.0,
      "contactid": "30717e9c-643f-ed11-9db0-002248225e95"
    }
  ]
}

応答では、@Microsoft.Dynamics.CRM.morerecords 注釈の値は、条件に一致するレコードがさらに存在することを示します。

@Microsoft.Dynamics.CRM.fetchxmlpagingcookie 注釈値は、返されたレコードに関するページング情報を提供します。 @Microsoft.Dynamics.CRM.fetchxmlpagingcookie 値は XML ドキュメントです。 次のリクエストでのドキュメントの pagingcookie 属性値を使う必要があります。

pagingcookie 属性値は、2 回 URL エンコードされます。 デコードされた値は次のようになります:

<cookie page="1"><fullname last="Robert Lyon (sample)" first="Susanna Stubberod (sample)" /><contactid last="{30717E9C-643F-ED11-9DB0-002248225E95}" first="{20717E9C-643F-ED11-9DB0-002248225E95}" /></cookie>

次のページ

前ページの @Microsoft.Dynamics.CRM.morerecords 注釈値は、さらにレコードがあることを示す後続のすべての要求で、以下に必要なことを示します。

  1. fetch エレメントの page 属性値をインクリメントする必要があります。

  2. pagingcookie 属性値を 2 回 URL デコードする必要があります。

  3. デコードされた pagingcookie 属性値を XML エンコードし、それを fetch エレメントの paging-cookie 属性の値として設定する必要があります。

    値を明示的に XML エンコードする必要があるかどうかは、使用するテクノロジによって異なります。 .NET では、XML 値を別の XML 要素の属性に設定する際、自動的に実行される場合があります。

  4. 最初の要求で行ったように、FetchXml 値全体を URL エンコードします。

次のリクエストでは、URLエンコードされる前の FetchXML は次のようになります。

<fetch page="2" count="3" mapping="logical" output-format="xml-platform" version="1.0" distinct="false" paging-cookie="&lt;cookie page=&quot;1&quot;&gt;&lt;fullname last=&quot;Robert Lyon (sample)&quot; first=&quot;Susanna Stubberod (sample)&quot; /&gt;&lt;contactid last=&quot;{30717E9C-643F-ED11-9DB0-002248225E95}&quot; first=&quot;{20717E9C-643F-ED11-9DB0-002248225E95}&quot; /&gt;&lt;/cookie&gt;">
  <entity name="contact">
    <attribute name="fullname" />
    <attribute name="jobtitle" />
    <attribute name="annualincome" />
    <order descending="true" attribute="fullname" />
    <filter type="and">
      <condition value="%(sample)%" attribute="fullname" operator="like" />
      <condition value="18717e9c-643f-ed11-9db0-002248225e95" attribute="parentcustomerid" operator="eq" />
    </filter>
  </entity>
</fetch>

要求:

GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%222%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22+paging-cookie%3D%22%26lt%3Bcookie+page%3D%26quot%3B1%26quot%3B%26gt%3B%26lt%3Bfullname+last%3D%26quot%3BRobert+Lyon+(sample)%26quot%3B+first%3D%26quot%3BSusanna+Stubberod+(sample)%26quot%3B+%2F%26gt%3B%26lt%3Bcontactid+last%3D%26quot%3B%7B30717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+first%3D%26quot%3B%7B20717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+%2F%26gt%3B%26lt%3B%2Fcookie%26gt%3B%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
  "@odata.count": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcount": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
  "@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
  "@Microsoft.Dynamics.CRM.fetchxmlpagingcookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25222%2522%253e%253cfullname%2520last%253d%2522Nancy%2520Anderson%2520%2528sample%2529%2522%2520first%253d%2522Rene%2520Valdes%2520%2528sample%2529%2522%2520%252f%253e%253ccontactid%2520last%253d%2522%257b24717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520first%253d%2522%257b38717E9C-643F-ED11-9DB0-002248225E95%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />",
  "@Microsoft.Dynamics.CRM.morerecords": true,
  "value": [
    {
      "@odata.etag": "W/\"74359736\"",
      "fullname": "Rene Valdes (sample)",
      "jobtitle": "Data Analyst III",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$86,000.00",
      "annualincome": 86000.0,
      "contactid": "38717e9c-643f-ed11-9db0-002248225e95"
    },
    {
      "@odata.etag": "W/\"74359726\"",
      "fullname": "Paul Cannon (sample)",
      "jobtitle": "Ski Instructor",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$68,500.00",
      "annualincome": 68500.0,
      "contactid": "34717e9c-643f-ed11-9db0-002248225e95"
    },
    {
      "@odata.etag": "W/\"74359686\"",
      "fullname": "Nancy Anderson (sample)",
      "jobtitle": "Activities Manager",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$55,500.00",
      "annualincome": 55500.0,
      "contactid": "24717e9c-643f-ed11-9db0-002248225e95"
    }
  ]
}

最後のページ

最後のページでは、@Microsoft.Dynamics.CRM.morerecords と @Microsoft.Dynamics.CRM.fetchxmlpagingcookie 注釈は応答に含まれません。

要求:

GET [Organization Uri]/api/data/v9.2/contacts?fetchXml=%3Cfetch+page%3D%223%22+count%3D%223%22+mapping%3D%22logical%22+output-format%3D%22xml-platform%22+version%3D%221.0%22+distinct%3D%22false%22+paging-cookie%3D%22%26lt%3Bcookie+page%3D%26quot%3B2%26quot%3B%26gt%3B%26lt%3Bfullname+last%3D%26quot%3BNancy+Anderson+(sample)%26quot%3B+first%3D%26quot%3BRene+Valdes+(sample)%26quot%3B+%2F%26gt%3B%26lt%3Bcontactid+last%3D%26quot%3B%7B24717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+first%3D%26quot%3B%7B38717E9C-643F-ED11-9DB0-002248225E95%7D%26quot%3B+%2F%26gt%3B%26lt%3B%2Fcookie%26gt%3B%22%3E%0D%0A++%3Centity+name%3D%22contact%22%3E%0D%0A++++%3Cattribute+name%3D%22fullname%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22jobtitle%22+%2F%3E%0D%0A++++%3Cattribute+name%3D%22annualincome%22+%2F%3E%0D%0A++++%3Corder+descending%3D%22true%22+attribute%3D%22fullname%22+%2F%3E%0D%0A++++%3Cfilter+type%3D%22and%22%3E%0D%0A++++++%3Ccondition+value%3D%22%25(sample)%25%22+attribute%3D%22fullname%22+operator%3D%22like%22+%2F%3E%0D%0A++++++%3Ccondition+value%3D%2218717e9c-643f-ed11-9db0-002248225e95%22+attribute%3D%22parentcustomerid%22+operator%3D%22eq%22+%2F%3E%0D%0A++++%3C%2Ffilter%3E%0D%0A++%3C%2Fentity%3E%0D%0A%3C%2Ffetch%3E&$count=true HTTP/1.1
Prefer: odata.include-annotations="*"
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

応答:

HTTP/1.1 200 OK
OData-Version: 4.0
Preference-Applied: odata.include-annotations="*"

{
  "@odata.context": "[Organization Uri]/api/data/v9.2/$metadata#contacts(fullname,jobtitle,annualincome,_transactioncurrencyid_value,transactioncurrencyid,contactid,transactioncurrencyid())",
  "@odata.count": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcount": 8,
  "@Microsoft.Dynamics.CRM.totalrecordcountlimitexceeded": false,
  "@Microsoft.Dynamics.CRM.globalmetadataversion": "74343461",
  "value": [
    {
      "@odata.etag": "W/\"74359696\"",
      "fullname": "Maria Cambell (sample)",
      "jobtitle": "Accounts Manager",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$31,000.00",
      "annualincome": 31000.0,
      "contactid": "28717e9c-643f-ed11-9db0-002248225e95"
    },
    {
      "@odata.etag": "W/\"74359746\"",
      "fullname": "Jim Glynn (sample)",
      "jobtitle": "Senior International Sales Manager",
      "annualincome@OData.Community.Display.V1.FormattedValue": "$81,400.00",
      "annualincome": 81400.0,
      "contactid": "3c717e9c-643f-ed11-9db0-002248225e95"
    }
  ]
}

バッチリクエスト内で使用 FetchXML

GET 要求内の URL の長さは 32 KB (32,768 文字) に制限されています。 URLにパラメータとして FetchXML を含めると、制限に達する可能性があります。 $batch リクエストを使用して操作を実行し、 POST URLから制限が適用されないリクエストの本文に FetchXML 移動することができます。 $batch 内での GET 要求の送信では、最大 64 KB (65,536 文字) の長さの URL を使用できます。 通常の GET リクエストよりもはるかに多くなりますが、無制限ではありません。 詳細: Web API を使用してバッチ操作を実行する。

例

要求:

POST [Organization URI]/api/data/v9.2/$batch HTTP/1.1
Content-Type:multipart/mixed;boundary=batch_AAA123
Accept:application/json
OData-MaxVersion:4.0
OData-Version:4.0

--batch_AAA123
Content-Type: application/http
Content-Transfer-Encoding: binary

GET [Organization URI]/api/data/v9.2/accounts?fetchXml=%3Cfetch%20mapping='logical'%3E%3Centity%20name='account'%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='name'/%3E%3Cattribute%20name='telephone1'/%3E%3Cattribute%20name='accountid'/%3E%3Cattribute%20name='creditonhold'/%3E%3C/entity%3E%3C/fetch%3E HTTP/1.1
Content-Type: application/json
OData-Version: 4.0
OData-MaxVersion: 4.0

--batch_AAA123--

応答:

--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34
Content-Type: application/http
Content-Transfer-Encoding: binary

HTTP/1.1 200 OK
Content-Type: application/json; odata.metadata=minimal
OData-Version: 4.0

{  
   "@odata.context":"[Organization URI]/api/data/v9.2/$metadata#accounts(accountid,name,telephone1,creditonhold)",
   "value":[  
      {  
         "@odata.etag":"W/\"563737\"",
         "accountid":"1f55c679-485e-e811-8151-000d3aa3c22a",
         "name":"Fourth Coffee (sample)",
         "telephone1":"+1-425-555-0121",
         "creditonhold":false
      },
      {  
         "@odata.etag":"W/\"563739\"",
         "accountid":"2555c679-485e-e811-8151-000d3aa3c22a",
         "name":"Litware, Inc. (sample)",
         "telephone1":"+1-425-555-0120",
         "creditonhold":false
      }
   ]
}
--batchresponse_cbfd44cd-a322-484e-913b-49e18af44e34--

参照

FetchXML を使用してクエリを構築します
Web API を使用したデータのクエリ
定義済みクエリの取得と実行

注意

ドキュメントの言語設定についてお聞かせください。 簡単な調査を行います。 (この調査は英語です)

この調査には約 7 分かかります。 個人データは収集されません (プライバシー ステートメント)。