Freigeben über

Ergebnisse mithilfe von FetchXml auslagern

  • Artikel

Sie können eine Grenze für die Anzahl der für jede Anfrage abgerufenen Zeilen festlegen, indem Sie eine Seitengröße festlegen. Mithilfe der Auslagerung können Sie aufeinanderfolgende Datenseiten abrufen, die alle Datensätze darstellen, die den Kriterien einer Abfrage entsprechen, und zwar auf leistungsstarke Weise.

Die standardmäßige und maximale Seitengröße beträgt 5.000 Zeilen. Wenn Sie keine Seitengröße festlegen, gibt Dataverse bis zu 5.000 Datenzeilen gleichzeitig zurück. Um mehr Zeilen zu erhalten, müssen Sie zusätzliche Anfragen senden.

Hinweis

Auslagerungsmodelle

Dataverse verfügt über zwei Auslagerungsmodelle: einfach und unter Verwendung von Auslagerungs-Cookies:

Einfach

  • Verwendet nur die Attribute Fetch-Element count und page
  • Nur für kleine Datasets geeignet
  • Es kann kein Dataset zurückgegeben werden, das größer als 50.000 Datensätze ist
  • Die Leistung nimmt mit zunehmender Zeilenanzahl ab

Auslagerungs-Cookies

Einfache Auslagerung

Sie können die erste Seite anfordern, indem Sie das Attribut Fetch-Element page auf 1 und das Attribut count auf die Seitengröße setzen, bevor Sie die Anforderung senden:

<fetch count='3' page='1'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />
  </entity>
</fetch>

Um die nächsten drei Datensätze zu erhalten, erhöhen Sie den Wert page und senden Sie eine weitere Anforderung.

<fetch count='3' page='2'>
  <entity name='account'>
    <attribute name='name' />
    <order attribute='name' />
    <order attribute='accountid' />    
  </entity>
</fetch>

Mit einer einfachen Auslagerung, manchmal auch als Legacy-Auslagerung bezeichnet, ruft Dataverse alle Ergebnisse der Abfrage bis zur aktuellen Seite ab, wählt die Anzahl der Datensätze aus, die für die Seite benötigt werden, und ignoriert dann den Rest. Dies ermöglicht ein schnelles Vor- und Zurückblättern der Daten oder das Springen zu einer bestimmten Seite. Allerdings ist die Gesamtzahl der Datensätze auf 50.000 begrenzt und es kann zu Leistungsproblemen bei komplexen Abfragen und willkürlich sortierten unterschiedlichen Abfrageergebnissen kommen.

Die einfache Auslagerung eignet sich gut für kleine Dataset, aber wenn die Anzahl der Zeilen im Dataset zunimmt, leidet die Leistung. Die Gesamtzahl der Zeilen, die mit der einfachen Auslagerung abgerufen werden können, beträgt 50.000. Für eine optimale Leistung empfehlen wir in jedem Fall die konsequente Verwendung von Auslagerungs-Cookies.

Auslagerungs-Cookies

Wenn nach der Anforderung der ersten Seite weitere Zeilen abzurufen sind, gibt Dataverse normalerweise ein Auslagerungs-Cookie zurück, das bei den folgenden Anforderungen für die nächsten Seiten verwendet wird.

Das Auslagerungs-Cookie enthält Daten zum ersten und letzten Datensatz in den Ergebnissen und hilft Dataverse dabei, die nächste Datenzeile so schnell wie möglich abzurufen und sollte verwendet werden, wenn es bereitgestellt wird. Sie sollten die Daten im Auslagerungs-Cookie nicht ändern, sondern einfach den Wert auf das Attribut Fetch-Element paging-cookie festlegen und den Attributwert page für nachfolgende Anforderungen erhöhen.

Abfragen, die keine Auslagerungs-Cookies unterstützen

Einige Abfragen unterstützen keine Auslagerungs-Cookies. Wenn Auslagerungs-Cookies von einer Abfrage nicht unterstützt werden, wird mit dem Ergebnis kein Auslagerungs-Cookie-Wert zurückgegeben. Beispielsweise unterstützen Abfragen, die nach einem link-entity-Attribut sortiert wurden, möglicherweise keine Auslagerungs-Cookies.

Wenn Dataverse kein Auslagerungs-Cookie zurückgibt, greift das Auslagerungsmodell auf eine einfache Auslagerungs zurück, mit allen damit verbundenen Einschränkungen.

Wie Sie Auslagerungs-Cookies verwenden, hängt davon ab, ob Sie das SDK für .NET oder die Web-API verwenden.

Die folgende statische RetrieveAll-Methode gibt alle Datensätze zurück, die mit der FetchXml-Abfrage übereinstimmen, und sendet mehrere Anforderungen, wenn die Anzahl der Datensätze die Seitengröße überschreitet.

Nach jeder Anforderung überprüft die Methode die EntityCollection.MoreRecords-Eigenschaft, um festzustellen, ob weitere Datensätze den Kriterien entsprechen. Wenn mehr Datensätze vorhanden sind, legt die Methode den Wert der zurückgegebenen EntityCollection.PagingCookie-Eigenschaft auf das paging-cookie-Attribut des Fetch-Elements fest und sendet eine weitere Anforderung.

/// <summary>
/// Returns all records matching the criteria
/// </summary>
/// <param name="service">The authenticated IOrganizationService instance.</param>
/// <param name="fetchXml">The fetchXml Query string</param>
/// <param name="pageSize">The page size to use. Default is 5000</param>
/// <returns>All the records that match the criteria</returns>
static EntityCollection RetrieveAll(IOrganizationService service, string fetchXml, int pageSize = 5000)
{

    // The records to return
    List<Entity> entities = new();

    XElement fetchNode = XElement.Parse(fetchXml);

    int page = 1; //Start with page 1

    //Set the page
    fetchNode.SetAttributeValue("page", page);

    // Set the page size
    fetchNode.SetAttributeValue("count", pageSize);

    while (true)
    {
        // Get the page
        EntityCollection results = service.RetrieveMultiple(new FetchExpression(fetchNode.ToString()));

        entities.AddRange(results.Entities);

        if (!results.MoreRecords)
        {
            break;
        }

        // Set the fetch paging-cookie attribute with the paging cookie from the previous query
        fetchNode.SetAttributeValue("paging-cookie", results.PagingCookie);

        fetchNode.SetAttributeValue("page", page++);
    }
    return new EntityCollection(entities);
}

Sie können das Beispiel Schnellstart: Eine SDK für .NET-Anforderung ausführen (C#) zum Testen von FetchXml-Abfragen mit den folgenden Schritten anpassen:

  1. Fügen Sie die statische RetrieveAll-Methode zur Program-Klasse hinzu.
  2. Ändern Sie die Main-Methode wie unten gezeigt:
static void Main(string[] args)
{
    using (ServiceClient serviceClient = new(connectionString))
    {
        if (serviceClient.IsReady)
        {
            //WhoAmIResponse response = 
            //    (WhoAmIResponse)serviceClient.Execute(new WhoAmIRequest());

            //Console.WriteLine("User ID is {0}.", response.UserId);

            string fetchQuery = @"<fetch count='3' page='1'>
                <entity name='contact'>
                    <attribute name='fullname'/>
                    <attribute name='jobtitle'/>
                    <attribute name='annualincome'/>
                    <order descending='true' attribute='fullname'/>
                </entity>
        </fetch>";

            EntityCollection records = RetrieveAll(service: serviceClient,
                        fetchXml: fetchQuery,
                        pageSize: 25);

            Console.WriteLine($"Success: {records.Entities.Count}");
        }
        else
        {
            Console.WriteLine(
                "A web service connection was not established.");
        }
    }

    // Pause the console so it does not close.
    Console.WriteLine("Press the <Enter> key to exit.");
    Console.ReadLine();
}

Wichtig

Diese Abfrage gibt ALLE Datensätze zurück, die den Kriterien entsprechen. Stellen Sie sicher, dass Sie Filterelemente einschließen, um die Ergebnisse einzuschränken.

Nächste Schritte,

Erfahren Sie, wie Sie Daten aggregieren können.

Aggregatdaten

Hinweis

Können Sie uns Ihre Präferenzen für die Dokumentationssprache mitteilen? Nehmen Sie an einer kurzen Umfrage teil. (Beachten Sie, dass diese Umfrage auf Englisch ist.)

Die Umfrage dauert etwa sieben Minuten. Es werden keine personenbezogenen Daten erhoben. (Datenschutzbestimmungen).