Conectarse a las API de SharePoint

En las soluciones de SharePoint Framework, es posible que tenga que interactuar con los datos almacenados en SharePoint. SharePoint ofrece un amplio conjunto de API que se pueden usar de varias formas. Este artículo describen las opciones disponibles, cómo funcionan, sus ventajas y desventajas.

Conectarse a la API de SharePoint con SPHttpClient

SharePoint Framework ofrece SPHttpClient que puede usar para conectarse a las API de REST de SharePoint. Una instancia lista para usar de SPHttpClient está disponible en el contexto de extensión y elementos web, y puede usarla para hacer todo tipo de solicitudes web. El fragmento de código siguiente muestra cómo podría usar SPHttpClient para recuperar el título del sitio actual:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`, SPHttpClient.configurations.v1)
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: {Title: string}): void => {
    console.log(web.Title);
  });

SPHttpClient ofrece la funcionalidad básica para realizar las solicitudes web más comunes. También permite configurar la solicitud mediante, por ejemplo, especificar encabezados de solicitud. Por ejemplo, si quiere enviar una solicitud web sin recuperar metadatos, usaría el código siguiente:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata.metadata=none']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Consideraciones sobre el uso de SPHttpClient

Al usar SPHttpClient, hay algunos aspectos que se deben tener en cuenta.

OData v4.0

De forma predeterminada, SPHttpClient usa la especificación OData v4 que requiere el uso de odata.metadata en lugar de solo odata para controlar los metadatos de respuesta. Si usa la directiva odata en el modo de OData v4, se producirá un error, como: El encabezado de HTTP ACEPTAR no está disponible o su valor no es válido.. Es posible establecer SPHttpClient en modo OData v3.0 estableciendo el encabezado de solicitud en el odata-version valor vacío:

this.context.spHttpClient
  .get(`${this.context.pageContext.web.absoluteUrl}/_api/web?$select=Title`,
    SPHttpClient.configurations.v1,
    {
      headers: [
        ['accept', 'application/json;odata=nometadata'],
        ['odata-version', '']
      ]
    })
  .then((res: SPHttpClientResponse): Promise<{ Title: string; }> => {
    return res.json();
  })
  .then((web: { Title: string }): void => {
    console.log(web.Title);
  });

Cookies de autenticación

En SharePoint Framework, hay varias clases para ejecutar solicitudes web. Dos de ellas son SPHttpClient y HttpClient. Una de las diferencias entre el SPHttpClient HttpClient es que SPHttpClient incluye las cookies de autenticación cuando se emiten solicitudes web. Como las API de SharePoint no son anónimas, debe proporcionar información de autenticación o recibirá una respuesta 401 No autorizado. Como HttpClient no incluye las cookies de autenticación en su solicitud, si se utiliza para llamar a las API de REST de SharePoint, las solicitudes producirán un error con una respuesta 401 No autorizado.

Parte de SharePoint Framework

SPHttpClient forma parte de SharePoint Framework y no se necesitan dependencias adicionales para empezar a usarla. Ya está disponible en la página, por lo que su uso no genera sobrecarga de rendimiento adicional en tiempo de ejecución.

Las consultas de REST sin procesar suelen producir errores

SPHttpClient ofrece asistencia básica para comunicarse con la API de REST de SharePoint. Si las aplicaciones necesitan solicitudes GET más complejas, POST solicita o utiliza funciones más avanzadas como el procesamiento por lotes. Notará rápidamente que usar SPHttpClient es complicado y suele producir errores. En tal caso, le recomendamos que use una alternativa, como la biblioteca PnPjs que ofrece una API fluida que puede comprobarse con TypeScript.

Conectarse a SharePoint con PnPjs

PnPjs es una biblioteca de JavaScript de código abierto para comunicarse con SharePoint y Microsoft 365. Expone una API fluida que permite utilizar fácilmente SharePoint y API de REST de Microsoft 365 de modo seguro. Para recuperar el título del sitio actual con PnPjs, se podría ejecutar el siguiente código:

const web = await sp.web
  .select('Title')
  .get<{Title: string;}>();
console.log(web.Title);

Nota:

PnPJS es una solución de código abierto con una comunidad activa que ofrece su soporte. No hay ningún contrato de nivel de servicio para el soporte de la herramienta de código abierto de Microsoft.

Observe que el código es menos detallado en comparación con SPHttpClient de SharePoint Framework y que todos los elementos de las solicitudes, excepto los nombres de las propiedades para recuperar, están fuertemente tipados, lo que reduce el riesgo de errores en tiempo de ejecución.

Para obtener más información sobre cómo configurar y usar PnPjs en SharePoint Framework, vea la documentación de PnPjs en https://pnp.github.io/pnpjs/.

Consideraciones de uso de PnPjs

Al decidir si debe usar PnPjs o no, estas son algunas consideraciones que debe tener en cuenta.

Las consultas de REST sin procesar suelen producir errores

Enviar solicitudes de REST sin procesar con SPHttpClient suele producir errores. Redactar las solicitudes correctas y analizar las respuestas será complicado, especialmente cuando su aplicación necesite ejecutar consultas POST o desee usar algunas funciones más avanzadas, como la solicitud de procesamiento por lotes. Además, la única manera de comprobar si las solicitudes son correctas es ejecutar el código en el explorador. Con PnPjs puede comunicarse con las API de SharePoint de modo seguro y usar las funciones avanzadas de la API de SharePoint fácilmente, lo que le permite centrarse en la creación de la aplicación en lugar de probar sus solicitudes.

Proyecto de código abierto

PnPjs es un proyecto de código abierto administrado por la comunidad de SharePoint. No hay ningún Acuerdo de Nivel de Servicio para usar PnPjs en las soluciones, y el soporte técnico de Microsoft no puede ayudarle con los posibles problemas causados por PnPjs. Dicho esto, PnPjs se desarrolla activamente y la comunidad responde rápidamente a todos los problemas y preguntas enviados.

Dependencia adicional

PnPjs es una dependencia adicional que necesita agregar a un proyecto y administrar a lo largo del tiempo. Tendrá que realizar un seguimiento de sus actualizaciones y actualizar el proyecto cuando sea necesario. La comunidad de PnPjs comunica periódicamente el estado del trabajo actual, las próximas versiones, y si hay algún impacto, en caso de actualizar a la versión más reciente.

Carga adicional

PnPjs ofrece un amplio conjunto de funciones para comunicarse con las API de SharePoint. La biblioteca admite las importaciones selectivas que permite mitigar, con una cuidadosa selección, el impacto global en el tamaño de su paquete Para obtener más información, consulte la documentación en https://pnp.github.io/pnpjs/.

  • Last updated on