Leer en inglés

Compartir a través de

No utilice el punto de conexión OData v2.0

  • Artículo

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:

Servicio de datos de la organización API Web
Hacer consultas de datos de Microsoft Dynamics CRM 2015 utilizando el punto de conexión de OData
Opciones de consulta del sistema OData mediante el punto de conexión de OData		 Consulta de datos
Propiedades de API web
Creando registros Crear una fila de tabla
Recuperar registros Recuperar una fila de tabla
Actualizar registros Actualización básica
Eliminar registros Eliminación básica
Usar inserción en profundidad Crea filas de tablas relacionadas en una sola operación
Actualizar propiedades individuales Actualizar un solo valor de propiedad
Asociación y desasociación de registros Asociar y desasociar filas de tabla
OData punto de conexión Códigos de estado HTTP Identificar códigos de estado

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:

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

Respuesta:

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
        }
      }
    ]
  }
}

Cuando se devuelvan más de 50 registros, use la propiedad __next para acceder a la página siguiente.

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'"

Crear registros

Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando crea registros.

Solicitud:

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
  }
}

Respuesta:

Con el servicio de datos de la organización, todas las propiedades se devuelven cuando se crea un registro.

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>

  }
}

Recuperar registros

Estos ejemplos muestran las diferencias entre el servicio de datos de la organización y la API web cuando recupera registros.

Solicitud:

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

Respuesta:

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
    }
  }
}

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:

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
  }
}

Respuesta:

HTTP 
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:

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

Respuesta:

HTTP 
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