Travail avec les données (aperçu)

[Cet article fait partie de la documentation en version préliminaire et peut faire l’objet de modifications.]

Dans cet article, nous montrons un exemple de code qui utilise le Kit de développement logiciel (SDK) pour utiliser des données et des métadonnées Dataverse. Veillez à lire la prise en main (préversion) avant de continuer avec cet article.

Opérations de base

Voici un exemple de code qui fonctionne sur la table de compte.

from azure.identity import InteractiveBrowserCredential
from PowerPlatform.Dataverse.client import DataverseClient

base_url = "https://<myorg>.crm.dynamics.com"
client = DataverseClient(base_url=base_url, credential=InteractiveBrowserCredential())

# Create an account and set some properties (returns list[str] of new GUIDs)
account_id = client.create("account", {"name": "Acme, Inc.", "telephone1": "555-0100"})[0]

# Read an account 
account = client.get("account", account_id)

# Update an account (returns None)
client.update("account", account_id, {"telephone1": "555-0199"})

# Delete an account
client.delete("account", account_id)

Opérations en bloc

Ici, nous montrons quelques exemples qui effectuent des mises à jour en bloc.

# Bulk update (broadcast) – apply same patch to several IDs
ids = client.create("account", [
    {"name": "Contoso"},
    {"name": "Fabrikam"},
])
client.update("account", ids, {"telephone1": "555-0200"})  # broadcast patch

# Bulk update (1:1) – list of patches matches list of IDs
client.update("account", ids, [
    {"telephone1": "555-1200"},
    {"telephone1": "555-1300"},
])
print({"multi_update": "ok"})

Ici, nous montrons un exemple qui crée plusieurs comptes. Transmettez une liste de charges utiles à create(logical_name, payloads) pour appeler l'action liée à la collection Microsoft.Dynamics.CRM.CreateMultiple. La méthode retourne list[str] des ID d’enregistrement créés.

# Bulk create accounts (returns list of GUIDs)
payloads = [
    {"name": "Contoso"},
    {"name": "Fabrikam"},
    {"name": "Northwind"},
]
ids = client.create("account", payloads)
assert isinstance(ids, list) and all(isinstance(x, str) for x in ids)
print({"created_ids": ids})

Informations supplémentaires sur les opérations en bloc :

• Retourne None (identique à la mise à jour unique) pour maintenir la cohérence sémantique.
• Diffusion ou par enregistrement déterminé selon que le paramètre changes est un dictionnaire ou une liste.
• L’attribut de clé primaire est injecté automatiquement lors de la construction des cibles d'action UpdateMultiple.
• Si une charge utile omet @odata.type, elle est étiquetée automatiquement (la recherche de nom logique mise en cache).
• La réponse inclut uniquement les ID : le KIT de développement logiciel (SDK) retourne ces chaînes GUID.
• La création d’un seul enregistrement retourne une liste comprenant un seul élément de GUIDs.
• La recherche @odata.type de métadonnées est effectuée une fois par jeu d’entités (mis en cache en mémoire).

Chargement du fichier

Voici quelques exemples de chargement d’un fichier nommé «test.pdf» dans la colonne Fichier nommée « sample_filecolumn » d’un enregistrement de compte. Le premier exemple concerne une taille de fichier inférieure à 128 Mo, tandis que le deuxième exemple concerne une taille de fichier supérieure à 128 Mo.

client.upload_file('account', record_id, 'sample_filecolumn', 'test.pdf')
client.upload_file('account', record_id, 'sample_filecolumn', 'test.pdf', mode='chunk', if_none_match=True)

Informations supplémentaires sur les chargements de fichiers :

• upload_file choisit l’une des trois méthodes à utiliser en fonction de la taille du fichier. Si la taille du fichier est inférieure à 128 Mo, le Kit de développement logiciel (SDK) utilise upload_file_small, sinon, le SDK utilise upload_file_chunk
• upload_file_small effectue un appel d’API web unique et prend uniquement en charge la taille < de fichier 128 Mo.
• upload_file_chunk utilise PATCH avec Content-Range pour charger le fichier (plus aligné sur la norme HTTP par rapport aux messages Dataverse). Il se compose de deux phases - 1. Demande PATCH pour obtenir les en-têtes utilisés pour le chargement réel et 2. Chargement réel en blocs. La fonction utilise OData x-ms-chunk-size retournée à la première étape pour déterminer la taille de bloc (normalement 4 Mo), puis utilise Content-Range et Content-Length comme métadonnées pour le chargement. Le nombre total d’appels d’API web est le nombre de blocs + 1.

Récupérer plusieurs éléments avec pagination

Utilisez la fonction get pour transmettre les résultats page par page. Vous pouvez limiter le total des résultats avec $top et indiquer la taille par page avec le page_size paramètre. Le Kit de développement logiciel (SDK) définit en interne l’en-tête de préférence OData odata.maxpagesize.

pages = client.get(
    "account",
    select=["accountid", "name", "createdon"],
    orderby=["name asc"],
    top=10,          # stop after 10 total rows (optional)
    page_size=3,     # ask for ~3 per page (optional)
)

total = 0
for page in pages: # each page is a list[dict]
    print({"page_size": len(page), "sample": page[:2]})
    total += len(page)
print({"total_rows": total})

Voici la liste des paramètres pris en charge où tous sont facultatifs, sauf logical_name.

• logical_name : str — Nom logique (singulier), par exemple « compte ».
• select: list[str] | None — Colonnes -> $select (séparé par des virgules).
• filter : str | None : OData $filter expression (par exemple, contains(name,'Acme') et statecode eq 0).
• orderby : list[str] | Aucun — Expressions de tri -> $orderby (joint à des virgules).
• top : int | Aucun : limite globale via $top (appliquée à la première demande ; le service s’applique sur plusieurs pages).
• expand : list[str] | Aucun — Extensions de navigation -> $expand ; passez des clauses brutes (par exemple, primarycontactid($select=fullname,emailaddress1)).
• page_size : int | Aucun : indicateur par page à l’aide de Prefer : odata.maxpagesize=<N> (non garanti ; la dernière page peut être plus petite).

Voici une liste de valeurs de retour et sémantiques.

• $select, $filter, $orderby, $expand, $top sont directement mappés aux options de requête OData correspondantes lors de la première requête.
• $top limite le nombre total de lignes ; le service peut partitionner ces lignes sur plusieurs pages.
• page_size (Prefer: odata.maxpagesize) est un indicateur ; le serveur décide des limites de page réelles.
• Retourne un générateur produisant des pages non vides (list[dict]). Les pages vides sont ignorées.
• Chaque liste retournée correspond à une page de valeur de l’API web.
• L’itération s’arrête lorsqu’aucun @odata.nextLink ne reste (ou lorsque la condition $top est satisfaite côté serveur).
• Le générateur ne matérialise pas tous les résultats ; les pages sont extraites de manière différée.

Voyons un exemple avec tous les paramètres pris en charge ainsi que la réponse attendue.

pages = client.get(
  "account",
  select=["accountid", "name", "createdon", "primarycontactid"],
  filter="contains(name,'Acme') and statecode eq 0",
  orderby=["name asc", "createdon desc"],
  top=5,
  expand=["primarycontactid($select=fullname,emailaddress1)"],
  page_size=2,
)

for page in pages:  # page is list[dict]
# Expected page shape (illustrative)
# [
# {
# "accountid": "00000000-0000-0000-0000-000000000001"
# "name": "Acme West"
# "createdon": "2025-08-01T12:34:56Z"
# "primarycontactid": {
# "contactid": "00000000-0000-0000-0000-0000000000aa"
# "fullname": "Jane Doe"
# "emailaddress1": "<jane@acme.com>"
# }
# "@odata.etag": "W/\"123456\""
# }
#
# ]
  print({"page_size": len(page)})

Métadonnées de table

Examinons un exemple de code pour utiliser une table personnalisée.

# Support enumerations with labels in different languages
class Status(IntEnum):
    Active = 1
    Inactive = 2
    Archived = 5
    __labels__ = {
        1033: {
            "Active": "Active",
            "Inactive": "Inactive",
            "Archived": "Archived",
        },
        1036: {
            "Active": "Actif",
            "Inactive": "Inactif",
            "Archived": "Archivé",
        }
    }

# Create a simple custom table and a few columns
info = client.create_table(
    "SampleItem",  # friendly name; defaults to SchemaName new_SampleItem
    {
        "code": "string",
        "count": "int",
        "amount": "decimal",
        "when": "datetime",
        "active": "bool",
        "status": Status,
    },
)

logical = info["entity_logical_name"]  # for example, "new_sampleitem"

# Create a record in the new table
# Set your publisher prefix (used when creating the table). If you used the default, it's "new".
prefix = "new"
name_attr = f"{prefix}_name"
id_attr = f"{logical}id"

rec_id = client.create(logical, {name_attr: "Sample A"})[0]

# Clean up
client.delete(logical, rec_id)          # delete record
client.delete_table("SampleItem")       # delete table (friendly name or explicit schema new_SampleItem)

Informations supplémentaires sur l’utilisation des métadonnées de table personnalisées :

• create retourne toujours une liste de GUID (longueur=1 pour une entrée unique).
• update et delete renvoient None pour des interfaces uniques et multiples.
• Passage d'une liste de payloads à create déclenche une création en bloc et retourne une liste[str] d'ID.
• get prend en charge la récupération d'un enregistrement unique à l’aide de l'ID d'enregistrement ou la pagination à travers les ensembles de résultats (privilégiez l'utilisation de 'select' pour limiter les colonnes).
• Pour les méthodes CRUD qui prennent un ID d’enregistrement, passez la chaîne GUID de 36 caractères avec tirets. Les parenthèses autour du GUID sont acceptées, mais pas obligatoires.

• Les requêtes SQL sont exécutées directement sur les points de terminaison d’ensemble d’entités à l’aide du ?sql= paramètre. Sous-ensemble pris en charge uniquement (SELECT unique, WHERE/TOP/ORDER BY facultatif, alias). Les constructions non prises en charge sont rejetées par le service.

Utilisation de pandas avec le Kit de développement logiciel (SDK)

PandasODataClient est un wrapper mince autour du client de bas niveau. Toutes les méthodes acceptent les noms logiques (singulier) (par exemple, compte, new_sampleitem), et non les noms de jeu d'entités (pluriel). Consultez l’exemple de référentiel source du SDK nommé « quickstart_pandas.py » pour un DataFrame flux de travail.

Informations connexes

• Exemples de code SDK pour Python
• SDK pour Python README

Voir aussi

• Démarrage (version préliminaire)
• Guide rapide de Dataverse (préversion)