Trabalhar com listas e itens de listas com REST

Pré-requisitos

Este tópico pressupõe que você já esteja familiarizado com os tópicos Conheça o serviço REST do Microsoft Office SharePoint Online e Concluir operações básicas usando pontos de extremidade REST do Microsoft Office SharePoint Online. Ele não fornece trechos de código.

Como recuperar listas e propriedades da lista com o REST

O exemplo a seguir mostra como recuperar uma lista específica, caso você tenha o GUID dela.

GET https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

O exemplo a seguir mostra como recuperar uma lista específica, caso você saiba o título dela.

GET https://{site_url}/_api/web/lists/GetByTitle('List Title')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

O XML a seguir mostra um exemplo das propriedades de lista que são retornadas quando você solicita o tipo de conteúdo de XML.

<content type="application/xml">
  <m:properties>
    <d:AllowContentTypes m:type="Edm.Boolean">true</d:AllowContentTypes>
    <d:BaseTemplate m:type="Edm.Int32">100</d:BaseTemplate>
    <d:BaseType m:type="Edm.Int32">0</d:BaseType>
    <d:ContentTypesEnabled m:type="Edm.Boolean">false</d:ContentTypesEnabled>
    <d:Created m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:Created>
    <d:DefaultContentApprovalWorkflowId m:type="Edm.Guid">00000000-0000-0000-0000-000000000000</d:DefaultContentApprovalWorkflowId>
    <d:Description>A list created by Project Based Retention used to store Project Policy Items.</d:Description>
    <d:Direction>none</d:Direction>
    <d:DocumentTemplateUrl m:null="true" />
    <d:DraftVersionVisibility m:type="Edm.Int32">0</d:DraftVersionVisibility>
    <d:EnableAttachments m:type="Edm.Boolean">true</d:EnableAttachments>
    <d:EnableFolderCreation m:type="Edm.Boolean">false</d:EnableFolderCreation>
    <d:EnableMinorVersions m:type="Edm.Boolean">false</d:EnableMinorVersions>
    <d:EnableModeration m:type="Edm.Boolean">false</d:EnableModeration>
    <d:EnableVersioning m:type="Edm.Boolean">false</d:EnableVersioning>
    <d:EntityTypeName>ProjectPolicyItemList</d:EntityTypeName>
    <d:ForceCheckout m:type="Edm.Boolean">false</d:ForceCheckout>
    <d:HasExternalDataSource m:type="Edm.Boolean">false</d:HasExternalDataSource>
    <d:Hidden m:type="Edm.Boolean">true</d:Hidden>
    <d:Id m:type="Edm.Guid">74de3ff3-029c-42f9-bd2a-1e9463def69d</d:Id>
    <d:ImageUrl>/_layouts/15/images/itgen.gif</d:ImageUrl>
    <d:IrmEnabled m:type="Edm.Boolean">false</d:IrmEnabled>
    <d:IrmExpire m:type="Edm.Boolean">false</d:IrmExpire>
    <d:IrmReject m:type="Edm.Boolean">false</d:IrmReject>
    <d:IsApplicationList m:type="Edm.Boolean">false</d:IsApplicationList>
    <d:IsCatalog m:type="Edm.Boolean">false</d:IsCatalog>
    <d:IsPrivate m:type="Edm.Boolean">false</d:IsPrivate>
    <d:ItemCount m:type="Edm.Int32">0</d:ItemCount>
    <d:LastItemDeletedDate m:type="Edm.DateTime">2012-06-26T23:15:58Z</d:LastItemDeletedDate>
    <d:LastItemModifiedDate m:type="Edm.DateTime">2012-06-26T23:15:59Z</d:LastItemModifiedDate>
    <d:ListItemEntityTypeFullName>SP.Data.ProjectPolicyItemListItem</d:ListItemEntityTypeFullName>
    <d:MultipleDataList m:type="Edm.Boolean">false</d:MultipleDataList>
    <d:NoCrawl m:type="Edm.Boolean">true</d:NoCrawl>
    <d:ParentWebUrl>/</d:ParentWebUrl>
    <d:ServerTemplateCanCreateFolders m:type="Edm.Boolean">true</d:ServerTemplateCanCreateFolders>
    <d:TemplateFeatureId m:type="Edm.Guid">00bfea71-de22-43b2-a848-c05709900100</d:TemplateFeatureId>
    <d:Title>Project Policy Item List</d:Title>
  </m:properties>
</content>

Trabalhar com listas usando REST

O exemplo a seguir mostra como criar uma lista.

POST https://{site_url}/_api/web/lists
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.List"
  },
  "AllowContentTypes": true,
  "BaseTemplate": 100,
 "ContentTypesEnabled": true,
 "Description": "My list description",
 "Title": "Test"
}

O exemplo a seguir mostra como atualizar uma lista usando o método MERGE.

POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.List"
  },
  "Title": "New title"
}

O exemplo a seguir mostra como criar um campo personalizado para uma lista.

POST https://{site_url}/_api/web/lists(guid'{list_guid}')/Fields
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Field"
  },
  "Title": "field title",
  "FieldTypeKind": FieldType value,
  "Required": "true/false",
  "EnforceUniqueValues": "true/false",
  "StaticName": "field name"
}

O exemplo a seguir mostra como excluir uma lista.

POST https://{site_url}/_api/web/lists(guid'{list_guid}')
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"
X-RequestDigest: "{form_digest_value}"

Alterações de coluna de pesquisa

Ao fazer referência a uma coluna de pesquisa dentro da lista usando API REST, use o nome de exibição de coluna de pesquisa em vez do nome interno.

GET https://{site_url}/_api/web/lists/getbytitle('ListName')/Items?&$filter=LookupColumnId eq 1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Trabalhar com itens de lista usando REST

Recuperar todos os itens de lista

O exemplo a seguir mostra como recuperar todos os itens de uma lista.

GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

Recuperar um item de lista específico

O exemplo a seguir mostra como recuperar um item específico de lista.

GET https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"

O XML a seguir mostra um exemplo das propriedades do item de lista que são retornadas quando você solicita o tipo de conteúdo XML.

<content type="application/xml">
  <m:properties>
    <d:FileSystemObjectType m:type="Edm.Int32">0</d:FileSystemObjectType>
    <d:Id m:type="Edm.Int32">1</d:Id>
    <d:ID m:type="Edm.Int32">1</d:ID>
    <d:ContentTypeId>0x010049564F321A0F0543BA8C6303316C8C0F</d:ContentTypeId>
    <d:Title>an item</d:Title>
    <d:Modified m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Modified>
    <d:Created m:type="Edm.DateTime">2012-07-24T22:47:26Z</d:Created>
    <d:AuthorId m:type="Edm.Int32">11</d:AuthorId>
    <d:EditorId m:type="Edm.Int32">11</d:EditorId>
    <d:OData__UIVersionString>1.0</d:OData__UIVersionString>
    <d:Attachments m:type="Edm.Boolean">false</d:Attachments>
    <d:GUID m:type="Edm.Guid">eb6850c5-9a30-4636-b282-234eda8b1057</d:GUID>
  </m:properties>
</content>

Obter itens como um fluxo

Obtém informações sobre a lista e seus dados. Usando esta API, você pode obter itens de lista caso eles usem campos complexos como pesquisas ou metadados gerenciados.

POST https://{site_url}/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json;odata=nometadata"

{
  "parameters": {
    "AddRequiredFields": "true",
    "DatesInUtc": "true",
    "RenderOptions": 17
  }
}

Parâmetros de URI RenderListDataAsStream

As propriedades a seguir podem ser adicionadas como parâmetros de cadeia de caracteres de consulta para manipular os dados retornados.

Propriedades do parâmetro do corpo RenderListDataAsStream

Opções do SPRenderListDataOptions

Exemplos

Recuperar item com uma ID específica

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&FilterField1=ID&FilterValue1=1
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...

Classificar itens em ordem decrescente por ID

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27&SortField=ID&SortDir=Desc
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
...

Recuperar itens da pasta especificada

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FOrders%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "FolderServerRelativeUrl": "/sites/team-a/lists/Orders/Europe"
  }
}

Recuperar o esquema da lista

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "RenderOptions": 4
  }
}

Recuperar informações sobre tipos de conteúdo de lista

POST https://{site_url}/sites/team-a/_api/web/GetList(@listUrl)/RenderListDataAsStream?@listUrl=%27%2Fsites%2Fteam-a%2Flists%2FList%27
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"
Content-Type: "application/json"

{
  "parameters": {
    "RenderOptions": 17
  }
}

Criar item de lista

O exemplo a seguir mostra como criar um item de lista.

GET https://{site_url}/_api/web/lists/GetByTitle('Test')?$select=ListItemEntityTypeFullName
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=nometadata"

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json;odata=verbose"
Content-Length: {length of request body as integer}
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Data.TestListItem"
  },
  "Title": "Test"
}

Criar item de lista em uma pasta

O exemplo a seguir mostra como criar um item de lista na pasta.

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/AddValidateUpdateItemUsingPath
Authorization: "Bearer " + accessToken
Accept          "application/json;odata=nometadata"
Content-Type    "application/json;odata=nometadata"
X-RequestDigest "The appropriate digest for current site"

{
  "listItemCreateInfo": {
    "FolderPath": {
      "DecodedUrl": "https://{site_url}/lists/Test/Folder/SubFolder"
    },
    "UnderlyingObjectType": 0
  },
  "formValues": [
    {
      "FieldName": "Title",
      "FieldValue": "Item"
    }
  ],
  "bNewDocumentUpdate": false
}

Solicitar detalhes da propriedade

Respostas

{
  "value": [
    {
      "ErrorMessage": null,
      "FieldName": "Title",
      "FieldValue": "Item",
      "HasException": false,
      "ItemId": 0
    },
    {
      "ErrorMessage": null,
      "FieldName": "Id",
      "FieldValue": "1",
      "HasException": false,
      "ItemId": 0
    }
  ]
}

A propriedade value contém a lista de propriedades que foram definidas ao criar o item de lista.

Atualizar item de lista

O exemplo a seguir mostra como atualizar um item de lista.

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
If-Match: "{etag or *}"
X-HTTP-Method: "MERGE"
X-RequestDigest: "{form_digest_value}"

{
  "__metadata": {
    "type": "SP.Data.TestListItem"
  },
  "Title": "TestUpdated"
}

Excluir item de lista

O exemplo a seguir mostra como excluir um item de lista.

POST https://{site_url}/_api/web/lists/GetByTitle('Test')/items({item_id})
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
If-Match: "{etag or *}"
X-HTTP-Method: "DELETE"

Usando valores ETag para determinar as versões do documento e do item de lista

O serviço REST do SharePoint, que segue o padrão OData, usa ETags de Cabeçalho de listas do SharePoint e itens de lista. Para verificar na versão de um item onde você realiza uma solicitação PUT, MERGE ou DELETE, especifique ETag no cabeçalho de solicitação HTTP If-Match.

Se o ETag especificado em sua solicitação não corresponder ao ETag do item de documento ou lista no servidor, o serviço REST retornará uma exceção 412, conforme a especificação do OData.

• Para forçar uma substituição do item independentemente da versão, defina o valor ETag como "*".
• Se você não especificar um ETag, o SharePoint substitui o item independentemente da versão.

No SharePoint, as ETags se aplicam apenas a listas do SharePoint e itens de lista.

Confira também

• Conheça o serviço REST do SharePoint
• SharePoint-Add-in-REST-OData-BasicDataOperations
• SharePoint: Realizar operações básicas de acesso a dados em arquivos e pastas usando REST
• Proteger acesso a dados e modelos de objeto cliente para suplementos do SharePoint
• Utilizar dados externos no SharePoint
• Recursos de OData
• Desenvolver suplementos do SharePoint