Associer et dissocier des lignes de tables à l’aide de l’API web

Article
08/24/2023

Vous pouvez associer des enregistrements individuels dans des lignes de table à d’autres enregistrements à l’aide de Relations qui existent entre les définitions de table. Dans OData, les Relations sont exprimés en tant que propriétés de navigation.

Vous pouvez découvrir quelles propriétés de navigation existent dans le document de service $metadata. Voir Propriétés de navigation de l’API web. Pour les tables Dataverse existantes, voir Web API EntityType Reference, pour chaque type d’entité, consultez les propriétés de navigation à valeur unique et à valeur de collection répertoriées.

Le tableau suivant décrit les trois types de Relations entre les tables dans Dataverse.

Type	Description	Exemple
Un-à-plusieurs	Un enregistrement peut être associé à plusieurs enregistrements.	Un enregistrement account peut avoir plusieurs enregistrements contact dans la propriété de navigation à valeur de collection `contact_customer_accounts`.
Plusieurs à un	De nombreux enregistrements peuvent être associés à un enregistrement. Une relation plusieurs-à-un est l’image miroir de la relation un-à-plusieurs. Il n’y a qu’une seule relation.	Plusieurs enregistrements contact peuvent être associés à un seul plusieurs enregistrement account à l’aide de la propriété de navigation à valeur unique `parentcustomerid_account`.
Plusieurs-à-plusieurs	De nombreux enregistrements peuvent être associés à de nombreux enregistrements.	Chaque security role (role) peut inclure des références à la définition d’un systemuser. Ces deux tables ont une propriété de navigation à valeur de collection `systemuserroles_association`.

Pour les enregistrements existants du côté plusieurs d’une relation un-à-plusieurs ou plusieurs-à-un, vous pouvez associer l’enregistrement en définissant une référence Uri à l’autre enregistrement. La façon la plus simple et la plus courante de le faire est d’ajouter l’annotation @odata.bind au nom de la propriété de navigation à valeur unique, puis définition de la valeur en tant qu’Uri pour l’autre enregistrement dans un demande PATCH.

Par exemple, pour associer un enregistrement contact à un account en utilisant la propriété de navigation à valeur unique parentcustomerid_account :

Demande :

PATCH [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "parentcustomerid_account@odata.bind": "accounts(ce9eaaef-f718-ed11-b83e-00224837179f)"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)

Comme décrit dans Association des lignes de table pendant la création, de nouveaux enregistrements peuvent également être associés à des enregistrements existants de la même manière.

Si vous souhaitez dissocier, vous pouvez simplement définir la valeur sur null.

Demande :

PATCH [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "parentcustomerid_account@odata.bind": null
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)

Quand vous dissociez de cette manière, vous n’avez pas besoin d’inclure l’annotation @odata.bind. Vous pouvez simplement utiliser le nom de la propriété de navigation à valeur unique :

Demande :

PATCH [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f) HTTP/1.1
If-Match: *
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "parentcustomerid_account": null
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0
OData-EntityId: [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)

More information: Mise à jour de base

Autres méthodes

Il existe d’autres moyens d’obtenir les mêmes résultats que ceux décrits ci-dessus avec des propriétés de navigation à valeur unique.

Vous pouvez utiliser la requête PUT suivante pour définir la valeur de la propriété de navigation à valeur unique parentcustomerid_account :

Demande :

PUT [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)/parentcustomerid_account/$ref HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "@odata.id": "[Organization URI]/api/data/v9.2/accounts(ce9eaaef-f718-ed11-b83e-00224837179f)"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Notes

Remarque : vous devez utiliser une URL absolue pendant la définition de la valeur de @odata.id.

Pour supprimer la référence, vous pouvez également utiliser cette requête DELETE :

Demande :

DELETE [Organization Uri]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)/parentcustomerid_account/$ref HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Avec OData, les deux côtés des relations plusieurs-à-plusieurs auront les propriétés de navigation avec une valeur de collection. Pour les relations un-à-plusieurs et plusieurs-à-un, la table une du côté "Un" aura une propriété de navigation à valeur de collection. Il n’y a aucune différence dans la manière dont vous travaillez avec l’un de ces types de Relations quand vous utilisez des propriétés de navigation à valeur de collection. Cette section décrit comment utiliser les propriétés de navigation à valeur de collection avec n’importe quel type de relation.

Ajouter un enregistrement à une collection

L’exemple suivant montre comment ajouter un enregistrement contact à la collection account contact_customer_accounts qui fait partie d’une relation un-à-plusieurs.

Demande :

POST [Organization Uri]/api/data/v9.2/accounts(ce9eaaef-f718-ed11-b83e-00224837179f)/contact_customer_accounts/$ref HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "@odata.id": "[Organization URI]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f)"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

L’exemple suivant montre comment ajouter un enregistrement role à la collection systemuser systemuserroles_association qui est une relation plusieurs-à-plusieurs.

Demande :

POST [Organization Uri]/api/data/v9.2/systemusers(34dcbaf5-f718-ed11-b83e-00224837179f)/systemuserroles_association/$ref HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

{
  "@odata.id": "[Organization URI]/api/data/v9.2/roles(886b280c-6396-4d56-a0a3-2c1b0a50ceb0)"
}

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Supprimer un enregistrement d’une collection

L’exemple suivant montre comment supprimer un enregistrement contact de la collection account contact_customer_accounts où la valeur contactid du contact est cf9eaaef-f718-ed11-b83e-00224837179f.

Demande :

DELETE [Organization Uri]/api/data/v9.2/accounts(ce9eaaef-f718-ed11-b83e-00224837179f)/contact_customer_accounts(cf9eaaef-f718-ed11-b83e-00224837179f)/$ref HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Ce qui suit fonctionne également :

Demande :

DELETE [Organization Uri]/api/data/v9.2/accounts(ce9eaaef-f718-ed11-b83e-00224837179f)/contact_customer_accounts/$ref?$id=[Organization URI]/api/data/v9.2/contacts(cf9eaaef-f718-ed11-b83e-00224837179f) HTTP/1.1
OData-MaxVersion: 4.0
OData-Version: 4.0
If-None-Match: null
Accept: application/json

Réponse :

HTTP/1.1 204 NoContent
OData-Version: 4.0

Voir aussi

Notes

Pouvez-vous nous indiquer vos préférences de langue pour la documentation ? Répondez à un court questionnaire. (veuillez noter que ce questionnaire est en anglais)

Le questionnaire vous prendra environ sept minutes. Aucune donnée personnelle n’est collectée (déclaration de confidentialité).

Associer et dissocier des lignes de tables à l’aide de l’API web

Utilisation des propriétés de navigation à valeur unique

Association avec une propriété de navigation à valeur unique

Dissociation avec une propriété de navigation à valeur unique

Autres méthodes

Utilisation des propriétés de navigation à valeur de collection

Ajouter un enregistrement à une collection

Supprimer un enregistrement d’une collection

Voir aussi

Commentaires

Ressources supplémentaires