Lire en anglais

Partager via

Interdiction d’utiliser le point de terminaison OData v2.0

  • Article

Catégorie : Supportabilité

Potentiel d’impact : Élevé

Symptômes

Il n’y a pas de symptômes immédiats, mais le code utilisant ce point de terminaison cessera de fonctionner lorsque le point de terminaison obsolète sera supprimé.

La date de suppression initiale était le 11 novembre 2022. Il a été prolongé jusqu’au 30 avril 2023. Nous avons décidé de ne pas supprimer le service le 30 avril 2023, afin de donner plus de temps aux utilisateurs pour faire passer leur code à l’utilisation de l’API Web. Si vous utilisez toujours ce point de terminaison, vous devez donner la priorité à la transition de votre code pour utiliser l’API Web afin d’être prêt lorsque la date de suppression finale sera annoncée. Plus d’informations : annonce de la date de suppression du service OData v2.0.

Conseils

Vous devez modifier tout code qui dépend du service de données d’organisation (OData v2.0) pour utiliser le point de terminaison d’API Web Dataverse (OData v4.0) à la place.

Pour les applications basées sur un modèle, vous devez utiliser Xrm.WebApi (référence d’API client), qui donne accès à l’API Web Dataverse pour les extensions côté client utilisant des ressources Web JavaScript.

Schémas problématiques

Le service de données d’organisation utilise ce point de terminaison : /XRMServices/2011/OrganizationData.svc. Vous devez rechercher tout code actif utilisant ce point de terminaison.

Le SDK Dynamics CRM fournit un exemple de bibliothèque JavaScript en tant que ressource Web JavaScript nommée sample_/Scripts/SDK.REST.js, que l’on trouve ici. Xrm.WebApi (référence d’API client) fournit des fonctions similaires pour créer, mettre à jour, supprimer et récupérer des enregistrements.

Les scripts PowerShell qui utilisent Invoke-WebRequest utilisent également le point de terminaison du service de données d’organisation.

Informations supplémentaires

Le service des données d’entreprise est un point de terminaison OData v2.0 introduit avec Dynamics CRM 2011. Il est déconseillé avec Dynamics 365 Customer Engagement v8.0. Aussi connu comme point de terminaison OData ou point de terminaison REPOS lors de sa sortie, ce point de terminaison permet uniquement d’effectuer des opérations de création, de récupération, de mise à jour et de suppression sur les tables.

L’API web Dataverse et le service de données d’organisation sont des points de terminaison OData, mais il existe des différences dans la façon dont ils sont implémentés. Ne vous attendez pas à ce que le code existant fonctionne avec seulement des modifications mineures.

Certaines des principales différences sont décrites dans les sections suivantes.

Noms de ressource

Les noms de ressources de l’API Web pour les tables sont basés sur EntitySetName. Les noms de service de données d’organisation avaient Set annexé à SchemaName.

API Web Service de données d’organisation
comptes AccountSet
contacts ContactSet
Tâches TaskSet

Noms de colonne

Les noms de colonnes dans l’API Web sont tous en minuscules et utilisent LogicalName. Dans le service de données d’organisation, les noms de colonne utilisent SchemaName.

Méthodes HTTP

Le service de données d’organisation utilise MERGE ou PUT plutôt que PATCH pour mettre à jour un enregistrement.

Format de données

Le service de données d’organisation prend en charge à la fois JSON et ATOM, un format basé sur XML généralement utilisé pour les flux RSS. L’API web prend uniquement en charge JSON.

Limite le nombre d’enregistrements renvoyés

Le service de données d’organisation ne renvoie que 50 enregistrements à la fois et ne permet pas de spécifier le format de page maximal.

L’API Web permet de définir un format de page maximal et renverra jusqu’à 5 000 enregistrements. Plus d’informations : Résultats de la page

Documentation héritée

Documentation du service de données d’organisation : SDK Microsoft Dynamics 2015 : utilisez le point de terminaison OData avec des ressources Web.

Le tableau suivant relie les zones associées pour le service de données d’organisation et l’API web :

Service de données d’organisation API Web
Demander les données Microsoft Dynamics CRM 2015 en utilisant le point de terminaison OData
Options de requête du système OData utilisant le point de terminaison OData		 Interroger les données
Propriétés de l’API web
Création d’enregistrements Créer une ligne de table
Récupération des enregistrements Récupérer une ligne de table
Mise à jour des enregistrements Mise à jour de base
Suppression des enregistrements Suppression de base
Utilisation de l’insertion profonde Créer des lignes de table associées en une seule opération
Mise à jour des propriétés individuelles Mettre à jour une valeur de propriété unique
Association et dissociation des enregistrements Associer et dissocier des lignes de table
Codes d’état HTTP du point de terminaison OData Identifier les codes de statut

Examples

Cette section met en évidence les différences entre l’utilisation du service de données d’organisation et l’API web.

Le service de données d’organisation prend uniquement en charge les opérations de création, de récupération, de mise à jour et de suppression sur les tables. Les exemples suivants illustrent les différences entre les services pour vous aider à migrer vers l’API Web.

Enregistrements de requête

Ces exemples montrent les différences entre le service de données d’organisation et l’API Web lorsque vous interrogez des enregistrements.

Le service de données de l’organisation n’a aucun moyen de gérer la pagination autre que d’utiliser $top et $skip. La taille de page maximale est de 50 enregistrements.

Demande :

HTTP 
GET  [Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode&$filter=PrimaryContactId/Id ne null&$top=2 HTTP/1.1
Accept: application/json

Réponse :

HTTP 
HTTP/1.1 200 OK
Cache-Control: no-cache
Allow: OPTIONS,GET,HEAD,POST
Content-Type: application/json;charset=utf-8

{
  "d": {
    "results": [
      {
        "__metadata": {
          "uri": " [Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'7a4814f9-b0b8-ea11-a812-000d3a122b89')",
          "type": "Microsoft.Crm.Sdk.Data.Services.Account"
        },
        "OwnershipCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": 2
        },
        "PrimaryContactId": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
          },
          "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
          "LogicalName": "contact",
          "Name": "Sam Smith",
          "RowVersion": null
        },
        "OpenDeals_Date": "/Date(1663715691000)/",
        "Telephone1": "555-1234",
        "NumberOfEmployees": 500,
        "Name": "Contoso, Ltd. (sample)",
        "AccountNumber": "1111",
        "DoNotPhone": false,
        "IndustryCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": 7
        }
      },
      {
        "__metadata": {
          "uri": " [Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'fed58509-4af3-ec11-bb3d-000d3a1a51c1')",
          "type": "Microsoft.Crm.Sdk.Data.Services.Account"
        },
        "OwnershipCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": null
        },
        "PrimaryContactId": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
          },
          "Id": "ffd58509-4af3-ec11-bb3d-000d3a1a51c1",
          "LogicalName": "contact",
          "Name": "Susie Curtis",
          "RowVersion": null
        },
        "OpenDeals_Date": "/Date(1663715691000)/",
        "Telephone1": null,
        "NumberOfEmployees": null,
        "Name": "Fourth Coffee",
        "AccountNumber": null,
        "DoNotPhone": false,
        "IndustryCode": {
          "__metadata": {
            "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
          },
          "Value": null
        }
      }
    ]
  }
}

Lorsque plus de 50 enregistrements sont renvoyés, utilisez la propriété __next pour accéder à la page suivante.

JSON 
"__next": "https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode&$filter=PrimaryContactId/Id ne null&$skiptoken=1,'accountid','%7B22153355-851D-ED11-B83E-000D3A572421%7D','%7B7A4814F9-B0B8-EA11-A812-000D3A122B89%7D'"

Créer des enregistrements

Ces exemples montrent les différences entre le service de données d’organisation et l’API Web lorsque vous créez des enregistrements.

Demande :

HTTP 
POST [Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet HTTP/1.1
Accept: application/json
Content-Type: application/json

{
  "OwnershipCode": {
    "Value": 2
  },
  "PrimaryContactId": {
    "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
    "LogicalName": "contact"
  },
  "OpenDeals_Date": "12/25/2022",
  "CustomerSizeCode": {
    "Value": 1
  },
  "Telephone1": "555-1234",
  "NumberOfEmployees": 500,
  "Name": "Contoso, Ltd. (sample)",
  "AccountNumber": "12225",
  "DoNotPhone": true,
  "IndustryCode": {
    "Value": 7
  }
}

Réponse :

Avec le service de données d’organisation, toutes les propriétés sont renvoyées à la création d’un enregistrement.

HTTP 
HTTP/1.1 201 Created
Content-Type: application/json;charset=utf-8
REQ_ID: a0c614be-50be-4c1e-9413-1c7ba459c5c9

{
  "d": {
    "__metadata": {
      "uri": "[Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'57d4d1af-7b38-ed11-9db0-002248296d7e')",
      "type": "Microsoft.Crm.Sdk.Data.Services.Account"
    },
    "AccountId": "57d4d1af-7b38-ed11-9db0-002248296d7e",

    <All properties are returned. Removed for brevity>

  }
}

Récupérer les enregistrements

Ces exemples montrent les différences entre le service de données d’organisation et l’API Web lorsque vous récupérez des enregistrements.

Demande :

HTTP 
GET https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')?$select=OwnershipCode,PrimaryContactId,OpenDeals_Date,Telephone1,NumberOfEmployees,Name,AccountNumber,DoNotPhone,IndustryCode HTTP/1.1
Accept: application/json

Réponse :

HTTP 
HTTP/1.1 200 OK

{
  "d": {
    "__metadata": {
      "uri": "https://[Organization URI]/xrmservices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e')",
      "type": "Microsoft.Crm.Sdk.Data.Services.Account"
    },
    "OwnershipCode": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
      },
      "Value": 2
    },
    "PrimaryContactId": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.EntityReference"
      },
      "Id": "dff27d1f-a61b-4bfe-a203-b2e5a36cda0e",
      "LogicalName": "contact",
      "Name": "Sam Smith",
      "RowVersion": null
    },
    "OpenDeals_Date": "/Date(1663784098000)/",
    "Telephone1": "555-1234",
    "NumberOfEmployees": 500,
    "Name": "Contoso, Ltd. (sample)",
    "AccountNumber": "12227",
    "DoNotPhone": true,
    "IndustryCode": {
      "__metadata": {
        "type": "Microsoft.Crm.Sdk.Data.Services.OptionSetValue"
      },
      "Value": 7
    }
  }
}

Mettre à jour les enregistrements

Ces exemples montrent les différences entre le service de données d’organisation et l’API Web lorsque vous mettez à jour des enregistrements.

Le service de données d’organisation nécessite que l’en-tête de demande X-HTTP-Method: MERGE soit appliqué avec une requête POST .

Demande :

HTTP 
POST https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
Accept: application/json
X-HTTP-Method: MERGE
Content-Type: application/json

{
  "OwnershipCode": {
    "Value": 3
  },
  "PrimaryContactId": {
    "Id": "6db0be2e-d01c-ed11-b83e-000d3a572421"
  },
  "OpenDeals_Date": "12/26/2022",
  "Telephone1": "555-1235",
  "NumberOfEmployees": 501,
  "Name": "Contoso, Ltd.",
  "AccountNumber": "12228",
  "DoNotPhone": false,
  "IndustryCode": {
    "Value": 6
  }
}

Réponse :

HTTP 
HTTP/1.1 204 No Content

Supprimer les enregistrements

Ces exemples montrent les différences entre le service de données d’organisation et l’API Web lorsque vous supprimez des enregistrements.

Demande :

HTTP 
DELETE https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
Accept: application/json

Réponse :

HTTP 
HTTP/1.1 204 No Content

Voir aussi

Comment utiliser Application Insights pour identifier l’utilisation du point de terminaison OrganizationData.svc dont le retrait est prévu en novembre 2022 (Forum Community)
Comment utiliser le contrôleur de solution pour identifier l’utilisation du point de terminaison OrganizationData.svc dont le retrait est prévu en novembre 2022 (Forum Community)
Utiliser l’API Web Microsoft Dataverse