Conectar-se a APIs do SharePoint

Nas suas soluções da Estrutura do SharePoint, você provavelmente desejará interagir com os dados armazenados no SharePoint. O SharePoint oferece um conjunto avançado de APIs que podem ser consumidas de várias formas. Este artigo descreve as opções disponíveis, como elas funcionam e as vantagens e desvantagens delas.

Conectar-se ao SharePoint usando o SPHttpClient

A Estrutura do SharePoint oferece o SPHttpClient que você pode usar para se conectar às APIs REST do SharePoint. Uma instância pronta para uso do SPHttpClient está disponível no contexto da extensão/web part, e você pode usá-la para executar todos os tipos de solicitações da Web. O trecho do código a seguir mostra como você usaria o SPHttpClient para recuperar o título do site atual:

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

O SPHttpClient oferece funcionalidade básica para executar as solicitações da Web mais comuns. Ele também permite que você configure sua solicitação, por exemplo, especificando cabeçalhos de solicitação. Por exemplo, se você quisesse fazer uma solicitação da Web sem recuperar os metadados, usaria o seguinte código:

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

Considerações para o uso do SPHttpClient

Ao usar o SPHttpClient, há algumas coisas que você deve levar em conta.

OData v4.0

Por padrão, o SPHttpClient usa a especificação OData v4, que requer o uso de odata.metadata em vez de somente odata para controlar os metadados de resposta. Se você usar a política odata no modo OData v4, receberá um erro, como: O cabeçalho HTTP ACCEPT está ausente ou o valor é inválido.. É possível definir o modo SPHttpClient como OData v3.0, definindo o cabeçalho de odata-version solicitação como valor vazio:

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 autenticação

Na Estrutura do SharePoint, há várias classes para executar solicitações da Web. Duas delas são o SPHttpClient e o HttpClient. Uma das diferenças entre o SPHttpClient e o HttpClient é que o SPHttpClient inclui cookies de autenticação ao emitir solicitações da Web. Como as APIs do SharePoint não são anônimas, você precisa fornecer informações de autenticação ou receberá a resposta 401 Não Autorizado. Como o HttpClient não inclui cookies de autenticação na solicitação, se você o usou para chamar as APIs REST do SharePoint, suas solicitações falharão com a resposta 401 Não Autorizado.

Parte da Estrutura do SharePoint

O SPHttpClient faz parte da Estrutura do SharePoint e dispensa quaisquer dependências adicionais para começar a usá-lo. Já está disponível na página, por isso seu uso não causa sobrecarga adicional de desempenho no tempo de execução.

Consultas REST brutas são sujeitas a erros

O SPHttpClient dá suporte básico para comunicação com a API REST do SharePoint. Se seus aplicativos exigirem solicitações GET mais complexas, solicitações POST ou usar recursos mais avançados, como envio em lote, você perceberá rapidamente que usar o SPHttpClient será complicado e sujeito a erros. Nesses casos, considere o uso de uma alternativa, como a biblioteca PnPjs, que oferece uma API fluente que pode ser verificada quanto à correção pelo TypeScript.

Conectar-se ao SharePoint usando PnPjs

PnPjs é uma biblioteca JavaScript de software livre para comunicação com o SharePoint e o Microsoft 365. Ela expõe uma API fluente que permite consumir facilmente as APIs REST do SharePoint e do Microsoft 365 de forma segura. Para recuperar o título do site atual usando PnPjs, você executaria o seguinte código:

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

Observação

O PnPJS é uma solução de software livre com uma comunidade ativa de suporte. Não há nenhuma SLA para o suporte da ferramenta de software livre por parte da Microsoft.

Observe como o código é menos detalhado em comparação com o SPHttpClient do SharePoint Framework e como todos os elementos das solicitações, exceto os nomes das propriedades a serem recuperadas, são fortemente tipados, reduzindo o risco de erros de tempo de execução.

Para obter mais informações sobre como configurar e usar PnPjs na Estrutura do SharePoint, confira a documentação de PnPjs em https://pnp.github.io/pnpjs/.

Considerações para usar PnPjs

Ao decidir se deve usar PnPjs ou não, veja abaixo algumas considerações para ter em conta.

Consultas REST brutas são sujeitas a erros

A emissão de solicitações REST brutas usando o SPHttpClient é propensa a erros. Especialmente, quando o aplicativo precisar executar consultas POST ou você quiser usar alguns dos recursos mais avançados, como solicitar envio em lote, redigir solicitações corretas e analisar as respostas. Para não mencionar, a única forma de verificar se as solicitações estão corretas é executando o código no navegador. Com PnPjs, é possível se comunicar com as APIs do SharePoint de forma segura e usar os recursos avançados da API do SharePoint, o que permite se concentrar na criação de seu aplicativo, em vez de testar as solicitações.

Projeto software livre

PnPjs é um projeto de software livre gerenciado pela comunidade do SharePoint. Não há SLA para usar PnPjs em suas soluções, e você não terá suporte da Microsoft para resolver possíveis problemas causados ​​por PnPjs. Assim, PnPjs é desenvolvido ativamente, e a comunidade responde rapidamente a todas as perguntas enviadas.

Dependência adicional

PnPjs é uma dependência adicional que você precisa adicionar ao seu projeto e gerenciar ao longo do tempo. É necessário acompanhar as atualizações e atualizar seu projeto quando necessário. A comunidade por trás de PnPjs comunica regularmente o estado do trabalho atual, as versões futuras e o impacto, se houver, da atualização para a versão mais recente.

Carga adicional

PnPjs oferece um avançado conjunto de recursos para comunicação com as APIs do SharePoint. A biblioteca dá suporte a importações seletivas para que, com a curadoria completa, o impacto geral no tamanho do pacote possa ser atenuado. Para obter mais informações, consulte a documentação emhttps://pnp.github.io/pnpjs/.

  • Last updated on