retrieveMultipleRecords (référence de l’API client)

Récupère une collection d’enregistrements de table.

Syntaxe

Xrm.WebApi.retrieveMultipleRecords(entityLogicalName, options, maxPageSize).then(successCallback, errorCallback);

Paramètres

Options

Les options de requête système suivantes sont prises en charge : $select, $top, $filter, $expand, et $orderby.

Utilisez l’option de requête système $expand pour contrôler quelles données des tables associées sont renvoyées. Si vous incluez uniquement le nom de la propriété de navigation, vous recevrez toutes les propriétés des enregistrements associés. Vous pouvez limiter les propriétés retournées pour les enregistrements associés à l’aide de l’option de requête système $select entre parenthèses après le nom de propriété de navigation. Utilisez cette procédure pour les propriétés de navigation à valeur unique et avec valeur de collection. Notez que pour le mode hors connexion, nous ne prenons en charge que l’option imbriquée $select à l’intérieur de l’option $expand.

Pour spécifier une FetchXML requête, utilisez la fetchXml colonne destinée à spécifier la requête.

Vous spécifiez les options de requête à partir de ?. Vous pouvez spécifier également plusieurs options de requête système en utilisant & pour séparer les options de requête.

Si vous spécifiez une chaîne de requête OData pour le paramètre options, la requête doit être codée pour les caractères spéciaux.

Lorsque vous spécifiez une FetchXML requête pour le options paramètre, la requête ne doit pas être codée.

Consultez les exemples plus loin dans cette rubrique pour savoir comment définir le paramètre options pour différents scénarios de récupération multiple.

Valeur renvoyée

En cas de réussite, retourne un objet de promesse à successCallback avec les propriétés suivantes :

Types d’attributs non pris en charge pour les options de requête OData dans Mobile Offline

Les types de colonnes suivants ne sont pas pris en charge lors d’une opération Xrm.WebApi.retrieveMultipleRecords avec les options de chaîne de requête OData (par exemple, $select et $filter) en mode mobile hors connexion. Vous devez utiliser FetchXML si le type d’attribut avec lequel vous devez travailler figure dans cette liste de types d’attributs non pris en charge.

• MultiSelectPicklist
• File
• Image
• ManagedProperty
• CalendarRules
• PartyList
• Virtual

Fonctionnalités non prises en charge dans Mobile Offline

Les fonctionnalités suivantes ne sont pas prises en charge dans Mobile Offline :

• Fonctionnalités de regroupement et d’agrégation

Opérations de filtrage prises en charge par type d’attribut dans Mobile Offline à l’aide de FetchXML

Les opérations suivantes sont prises en charge pour tous les types d’attributs lorsque vous travaillez avec FetchXML :

• Égal (eq)
• Différent de (neq)
• Null (null)
• Not Null (not-null)

Le tableau suivant répertorie davantage d’opérations prises en charge pour chaque type d’attribut :

Exemples

La plupart des scénarios/exemples mentionnés dans Interroger les données à l’aide de l’API Web peuvent être réalisés à l’aide de la méthode retrieveMultipleRecords . Certains des exemples sont répertoriés ci-dessous.

Récupération multiple de base

Cet exemple interroge la table des comptes définie et utilise les options de requête système $select et $top pour renvoyer la propriété name pour les trois premiers comptes :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$top=3").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Récupération de base multiple avec FetchXML

Cet exemple interroge l’entité account à l’aide de fetchXML.

var fetchXml = "?fetchXml=<fetch mapping='logical'><entity name='account'><attribute name='accountid'/><attribute name='name'/></entity></fetch>";

Xrm.WebApi.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Récupérer ou filtrer par les propriétés de recherche

Pour la plupart des propriétés de navigation à valeur unique, vous trouverez une propriété en lecture seule calculée qui utilise la convention d’affectation de noms suivante : _<name>_value où <name> est le nom de la propriété de navigation à valeur unique. Aux fins du filtrage, la valeur spécifique de la propriété de navigation à valeur unique peut également être utilisée. Cependant, pour les clients mobiles en mode hors connexion, ces options de syntaxe ne sont pas prises en charge et le nom de la propriété de navigation à valeur unique doit être utilisé à la fois pour la récupération et le filtrage. En outre, la comparaison des propriétés de navigation à Null n’est pas prise en charge en mode hors connexion.

Pour plus d’informations : Propriétés de recherche

Voici des exemples de codes pour les scénarios suivants :

Pour le scénario en ligne (connecté au serveur)

Cet exemple interroge la table des comptes définie et utilise les options de requête système $select et $filter pour renvoyer le nom et la propriété primarycontactid pour les comptes qui ont un contact principal spécifique :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name,_primarycontactid_value&$filter=primarycontactid/contactid eq a0dbf27c-8efb-e511-80d2-00155db07c77").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Pour le scénario hors ligne mobile

Cet exemple interroge la table des comptes définie et utilise les options de requête système $select et $filter pour renvoyer le nom et la propriété primarycontactid pour les comptes qui ont un contact principal spécifique dans le cas du mode hors ligne :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name,primarycontactid&$filter=primarycontactid eq a0dbf27c-8efb-e511-80d2-00155db07c77").then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Utilisation FetchXML pour récupérer ou filtrer par propriétés de recherche (scénario en ligne et hors ligne)

Vous pouvez utiliser le paramètre FetchXML en ligne ou hors ligne pour récupérer la propriété name et primarycontactid pour les enregistrements de compte dont le contact principal correspond à une condition :

var fetchXml = `?fetchXml=
    <fetch mapping='logical'>
       <entity name='account'>
          <attribute name='name'/>
          <attribute name='primarycontactid'/>
          <link-entity name='contact' from='contactid' to='primarycontactid'>
             <filter type='and'>
                <condition attribute='lastname' operator='eq' value='Contoso'/>
             </filter>
          </link-entity>
       </entity>
    </fetch>`;

Xrm.WebApi.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }                    

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Spécifier le nombre de tables à renvoyer dans une page

L’exemple suivant montre l’utilisation du paramètre maxPageSize pour spécifier le nombre d’enregistrements (3) à afficher dans une page.

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }
        console.log("Next page link: " + result.nextLink);
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Cet exemple affiche trois enregistrements et un lien vers la page suivante. Voici un exemple de résultat de la Console dans les outils de développement de navigateur :

{@odata.etag: "W/"1035541"", name: "A. Datum", accountid: "475b158c-541c-e511-80d3-3863bb347ba8"}
@odata.etag: "W/"1035541""accountid: "475b158c-541c-e511-80d3-3863bb347ba8"name: "A. Datum"__proto__: Object
VM5595:4 
{@odata.etag: "W/"947306"", name: "Adventure Works", accountid: "a8a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:4 
{@odata.etag: "W/"1033754"", name: "Alpine Ski House", accountid: "aaa19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5595:6 
Next page link: [Organization URI]/api/data/v9.0/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

Utilisez la partie de la requête dans l’URL dans la propriété nextLink comme valeur pour le paramètre options dans votre appel suivant retrieveMultipleRecords pour demander le prochain jeu d’enregistrements. Ne modifiez ou n’ajoutez aucune autre option de requête système à la valeur. Pour chaque demande de pages supplémentaires consécutive, vous devez utiliser la même valeur maxPageSize que celle utilisée dans la requête de récupération multiple. En outre, placez les résultats renvoyés ou la valeur de la propriété nextLink dans le cache de sorte que les pages récupérées précédemment puissent être renvoyées.

Par exemple, pour obtenir la page d’enregistrements suivante, vous devez passer dans la partie de la requête de l’URL nextLink le paramètre options :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$skiptoken=%3Ccookie%20pagenumber=%222%22%20pagingcookie=%22%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257bAAA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257b475B158C-541C-E511-80D3-3863BB347BA8%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }
        console.log("Next page link: " + result.nextLink);
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Cela renvoie la page suivante du resultset :

{@odata.etag: "W/"1035542"", name: "Blue Yonder Airlines", accountid: "aca19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:4 
{@odata.etag: "W/"1031348"", name: "City Power & Light", accountid: "aea19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:4 
{@odata.etag: "W/"1035543"", name: "Coho Winery", accountid: "b0a19cdd-88df-e311-b8e5-6c3be5a8b200"}
VM5597:6 
Next page link: [Organization URI]/api/data/v9.0/accounts?$select=name&$skiptoken=%3Ccookie%20pagenumber=%223%22%20pagingcookie=%22%253ccookie%2520page%253d%25222%2522%253e%253caccountid%2520last%253d%2522%257bB0A19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520first%253d%2522%257bACA19CDD-88DF-E311-B8E5-6C3BE5A8B200%257d%2522%2520%252f%253e%253c%252fcookie%253e%22%20istracking=%22False%22%20/%3E

FetchXML Exemple (scénario en ligne)

L’exemple suivant illustre l’utilisation du paramètre count du paramètre FetchXML pour spécifier le nombre d’enregistrements (3) à afficher dans une page.

var fetchXml = "?fetchXml=<fetch mapping='logical' count='3'><entity name='account'><attribute name='accountid'/><attribute name='name'/></entity></fetch>";

Xrm.WebApi.online.retrieveMultipleRecords("account", fetchXml).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }          

        console.log("Paging cookie: " + result.fetchXmlPagingCookie);

        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Cet exemple affichera trois enregistrements et renverra un cookie de pagination pour récupérer les résultats de la page suivante s’il existe plusieurs enregistrements appartenant à l’ensemble de résultats. FetchXML Voici un exemple de résultat de la Console dans les outils de développement de navigateur :

{
   "entities": [
      {
         "@odata.etag": "W/\"1035542\"",
         "accountid": "aca19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "Blue Yonder Airlines"
      },
      {
         "@odata.etag": "W/\"1031348\"",
         "accountid": "aea19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "City Power & Light"
      },
      {
         "@odata.etag": "W/\"1035543\"",
         "accountid": "b0a19cdd-88df-e311-b8e5-6c3be5a8b200",
         "name": "Coho Winery"
      }
   ],
   "fetchXmlPagingCookie": "<cookie pagenumber=\"2\" pagingcookie=\"%253ccookie%2520page%253d%25221%2522%253e%253caccountid%2520last%253d%2522%257b0748C6EC-55A8-EB11-B1B5-000D3AFEF6FA%257d%2522%2520first%253d%2522%257bFC47C6EC-55A8-EB11-B1B5-000D3AFEF6FA%257d%2522%2520%252f%253e%253c%252fcookie%253e\" istracking=\"False\" />"
}

Nous pouvons utiliser le fetchXmlPagingCookie comme indiqué dans l’exemple ci-dessous pour récupérer de grands ensembles de résultats avec pagination.

function CreateXml(fetchXml, pagingCookie, page, count) {
  var domParser = new DOMParser();
  var xmlSerializer = new XMLSerializer();

  var fetchXmlDocument = domParser.parseFromString(fetchXml, "text/xml");

  if (page) {
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute("page", page.toString());
  }

  if (count) {
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute("count", count.toString());
  }

  if (pagingCookie) {
    var cookieDoc = domParser.parseFromString(pagingCookie, "text/xml");
    var innerPagingCookie = domParser.parseFromString(
      decodeURIComponent(
        decodeURIComponent(
          cookieDoc
            .getElementsByTagName("cookie")[0]
            .getAttribute("pagingcookie")
        )
      ),
      "text/xml"
    );
    fetchXmlDocument
      .getElementsByTagName("fetch")[0]
      .setAttribute(
        "paging-cookie",
        xmlSerializer.serializeToString(innerPagingCookie)
      );
  }

  return xmlSerializer.serializeToString(fetchXmlDocument);
}

function retrieveAllRecords(entityName, fetchXml, page, count, pagingCookie) {
  if (!page) {
    page = 0;
  }

  return retrievePage(entityName, fetchXml, page + 1, count, pagingCookie).then(
    function success(pageResults) {
      if (pageResults.fetchXmlPagingCookie) {
        return retrieveAllRecords(
          entityName,
          fetchXml,
          page + 1,
          count,
          pageResults.fetchXmlPagingCookie
        ).then(
          function success(results) {
            if (results) {
              return pageResults.entities.concat(results);
            }
          },
          function error(e) {
            throw e;
          }
        );
      } else {
        return pageResults.entities;
      }
    },
    function error(e) {
      throw e;
    }
  );
}

function retrievePage(entityName, fetchXml, pageNumber, count, pagingCookie) {
  var fetchXml =
    "?fetchXml=" + CreateXml(fetchXml, pagingCookie, pageNumber, count);

  return Xrm.WebApi.online.retrieveMultipleRecords(entityName, fetchXml).then(
    function success(result) {
      return result;
    },
    function error(e) {
      throw e;
    }
  );
}

var count = 3;
var fetchXml =
  '<fetch mapping="logical"><entity name="account"><attribute name="accountid"/><attribute name="name"/></entity></fetch>';

retrieveAllRecords("account", fetchXml, null, count, null).then(
  function success(result) {
    console.log(result);

    // perform additional operations on retrieved records
  },
  function error(error) {
    console.log(error.message);
    // handle error conditions
  }
);

Extraire les tables associées en développant des propriétés de navigation

Utilisez l’option de requête système $expand dans les propriétés de navigation pour contrôler quelles données sont renvoyées à partir des tables liées. L’exemple suivant montre comment récupérer le contact pour tous les enregistrements de compte. Pour les enregistrements de contact associés, nous récupérons uniquement contactid et fullname :

Xrm.WebApi.retrieveMultipleRecords("account", "?$select=name&$top=3&$expand=primarycontactid($select=contactid,fullname)", 3).then(
    function success(result) {
        for (var i = 0; i < result.entities.length; i++) {
            console.log(result.entities[i]);
        }        
        // perform additional operations on retrieved records
    },
    function (error) {
        console.log(error.message);
        // handle error conditions
    }
);

Le morceau de code ci-dessus renvoie un résultat avec un schéma comme suit :

{
   "entities": [
      {
         "@odata.etag": "W/\"1459919\"",
         "name": "Test Account",
         "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
         "primarycontactid": {
            "contactid": "6c63a1b7-19c6-ea11-a81a-000d3af5e732",
            "fullname": "Test Contact"
         }
      }
   ]
}

Méthode obsolète pour le scénario hors ligne mobile

Une opération $expand hors connexion retourne une annotation @odata.nextLink contenant des informations sur la façon d’accéder aux informations de l’enregistrement associé. Nous utilisons les paramètres id, entityType et options de cette annotation pour construire une ou plusieurs requêtes Xrm.WebApi.offline.retrieveRecord supplémentaires. Le morceau de code suivant fournit un exemple complet de la façon de procéder :

Xrm.WebApi.offline.retrieveMultipleRecords("account", "?$select=name&$top=3&$expand=primarycontactid($select=contactid,fullname)").then(function(resultSet) {
    /**
     *  resultSet has a structure like:
     *  {
     *      "entities": [
     *          {
     *              "accountid": "119edfac-19c6-ea11-a81a-000d3af5e732",
     *              "name": "Test Account",
     *              "primarycontactid@odata.nextLink": {
     *                  "API": "{Xrm.Mobile.offline}.{retrieveRecord}",
     *                  "id": "119edfac-19c6-ea11-a81a-000d3af5e732",
     *                  "entityType": "account",
     *                  "options": "?$select=accountid&$expand=primarycontactid($select=contactid,fullname)&$getOnlyRelatedEntity=true"
     *              },
     *              "primarycontactid": {}
     *          }
     *      ]
     *  }
     *
     *  Notice the empty `primarycontactid` property but an additional `primarycontactid@odata.nextLink` 
     *  annotation that lets us know how to get to the linked data that we need.
     **/

    var promises = resultSet.entities.map(function(outerItem) {
        // We do a retrieveRecord() for every item in the result set of retrieveMultipleRecords() and then
        // combine the results into the retrieveMultipleRecords() result set itself.
       return Xrm.WebApi.offline.retrieveRecord(
           outerItem["primarycontactid@odata.nextLink"].entityType, 
           outerItem["primarycontactid@odata.nextLink"].id,
           outerItem["primarycontactid@odata.nextLink"].options
        ).then(function(innerResult) {            
            if (innerResult.value.length === 0) {
                return outerItem;
            }
            outerItem.primarycontactid = innerResult.value[0];
            return outerItem;
        });
    });

    return Promise.all(promises);
}).then(function(allResults) {
    for (var i = 0; i < allResults.length; i++) {
        console.log(allResults[i]);
    }
    // perform additional operations on retrieved records
}, function(error) {
    console.error(error);
    // handle error conditions
});

Pour plus d’exemples de récupération de plusieurs enregistrements à l’aide de l’API Web, voir Interroger des données à l’aide de l’API Web.

Articles associés

Interroger des données à l’aide de l’API Web
Xrm.webApi.retrieveRecord
Xrm.webApi