No utilice el punto de conexión OData v2.0
Categoría: Compatibilidad
Potencial de impacto: alto
Síntomas
No hay síntomas inmediatos, pero el código que usa este punto de conexión dejará de funcionar cuando se elimine el punto de conexión obsoleto.
La fecha de eliminación original era el 11 de noviembre de 2022. Se prorrogó hasta el 30 de abril de 2023. Decidimos no eliminar el servicio el 30 de abril de 2023 para darles a las personas más tiempo para hacer la transición de su código para usar la API web. Si aún usa este punto de conexión, debe priorizar la transición de su código para usar la API web para estar preparado cuando se anuncie la fecha final de eliminación. Más información: Anuncio de la fecha de eliminación del servicio OData v2.0.
Instrucciones
Debe cambiar cualquier código que dependa de la Organización Data Service (OData v2.0) para usar el punto de conexión de la API web Dataverse (OData v4.0) en su lugar.
Para aplicaciones basadas en modelos, debe usar Xrm.WebApi (referencia de API de cliente), que proporciona acceso a la API web Dataverse para extensiones del lado del cliente que utilizan recursos web de JavaScript.
Patrones problemáticos
El servicio de datos de la Organización Data Service usa este punto de conexión: /XRMServices/2011/OrganizationData.svc
. Debes buscar cualquier código activo que usa este punto de conexión.
Dynamics CRM SDK proporcionó una biblioteca de JavaScript de ejemplo como un recurso web de JavaScript denominado sample_/Scripts/SDK.REST.js
, que se puede encontrar aquí. El Xrm.WebApi (referencia de API de cliente) proporciona funciones similares para crear, actualizar, eliminar y recuperar registros.
Los scripts de PowerShell que usan Invoke-WebRequest a veces también usan el punto de conexión de la Organización Data Service.
Información adicional
El Organization Data Service es un punto de conexión OData v2.0 que se introdujo con Dynamics CRM 2011. Quedó en desuso con Dynamics 365 Customer Engagement v8.0. También conocido como el punto de conexión OData o punto de conexión REST cuando se publicó, este punto de conexión solo admite creación, recuperación, actualización y eliminación en tablas.
La API web de Dataverse y el servicio de datos de la organización son puntos finales de OData, pero existen diferencias en la forma en que se implementan. No espere que el código existente funcione solo con cambios menores.
Algunas de las principales diferencias se describen en las secciones a continuación.
Nombre de recurso
Los nombres de los recursos de la API web para las tablas se basan en EntitySetName. Los nombres de los servicios de datos de la organización tenían Set
adjunto al SchemaName.
API Web | Servicio de datos de la organización |
---|---|
cuentas | AccountSet |
contactos | ContactSet |
Tareas de | TaskSet |
Nombre de columna
Los nombres de las columnas en la API web están todos en minúsculas y usan LogicalName. En el servicio de datos de la organización, los nombres de columna usan SchemaName.
Métodos HTTP
El servicio de datos de la organización usa MERGE
o PUT
en vez de PATCH
para actualizar un registro.
Formato de datos
El servicio de datos de la organización es compatible tanto con JSON como con ATOM, un formato basado en XML que generalmente se usa para las fuentes RSS. La API web solo admite JSON.
Límites en el número de registros devueltos
La Organización Data Service solo devolverá 50 registros a la vez y no proporciona una forma de especificar el tamaño máximo de página.
La API web permite establecer un tamaño máximo de página y devolverá hasta 5000 registros. Más información: Resultados de la página
Documentación heredada
Documentación del servicio de datos de la organización: Microsoft Dynamics 2015 SDK: use OData punto de conexión con recursos web.
La siguiente tabla conecta las áreas relacionadas para el servicio de datos de la organización y la API web:
Ejemplos
Esta sección destaca las diferencias entre el uso del servicio de datos de la organización y la API web.
El servicio de datos de la organización solo admite operaciones de creación, recuperación, actualización y eliminación en tablas. Los siguientes ejemplos ilustran las diferencias entre los servicios para ayudarlo a migrar a la API web.
Consultar registros
Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando consulta registros.
El Servicio de datos de la organización no tiene otra forma de administrar la paginación que no sea mediante $top
y $skip
. El tamaño máximo de página es de 50 registros.
Solicitud:
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
Respuesta:
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
}
}
]
}
}
Cuando se devuelvan más de 50 registros, use la propiedad __next
para acceder a la página siguiente.
"__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'"
Crear registros
Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando crea registros.
Solicitud:
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
}
}
Respuesta:
Con el servicio de datos de la organización, todas las propiedades se devuelven cuando se crea un registro.
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>
}
}
Recuperar registros
Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando recupera registros.
Solicitud:
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
Respuesta:
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
}
}
}
Actualizar registros
Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando actualiza registros.
El servicio de datos de la organización requiere que el encabezado de solicitud X-HTTP-Method: MERGE
se aplique con una solicitud POST
.
Solicitud:
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
}
}
Respuesta:
HTTP/1.1 204 No Content
Eliminar registros
Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando elimina registros.
Solicitud:
DELETE https://[Organization URI]/XRMServices/2011/OrganizationData.svc/AccountSet(guid'b68d56a6-4739-ed11-9db0-002248296d7e') HTTP/1.1
Accept: application/json
Respuesta:
HTTP/1.1 204 No Content
Consulte también
Cómo utilizar Application Insights para identificar el uso del punto de conexión OrganizationData.svc, cuyo retiro está previsto para noviembre de 2022 (Foro de la comunidad)
Cómo utilizar Solution Checker para identificar el uso del punto de conexión OrganizationData.svc, cuyo retiro está previsto para noviembre de 2022 (Foro de la comunidad)
Usar la API web de Microsoft Dataverse