Determinar los URI de punto de conexión de servicio REST de SharePoint
Sugerencia
Antes de empezar, vea los recursos siguientes:
Introducción al servicio REST para SharePointNavegar por la estructura de datos de SharePoint representada en el servicio REST
Estructura del URI de punto de conexión de REST de SharePoint
Antes de poder obtener acceso a un recurso de SharePoint mediante el servicio REST, primero debe averiguar el extremo de URI que apunta a dicho recurso. Cada vez que sea posible, el URI de estos extremos de REST imita rigurosamente la firma de la API del recurso en el modelo de objetos de cliente de SharePoint. Por ejemplo:
Sin embargo, en algunos casos, el URI de extremo difiere de la correspondiente firma del modelo de objetos de cliente, con el objetivo de cumplir con las convenciones de REST o de OData.
En la ilustración siguiente se muestra la estructura de sintaxis general de los URI de REST de SharePoint.
Estructura de sintaxis de URI de REST de SharePoint**
Algunos puntos de conexión para recursos de SharePoint se desvían de esta estructura de sintaxis:
- Métodos que requieren tipos complejos como parámetros. Si el método del modelo de objetos de cliente correspondiente requiere que se pasen tipos complejos como parámetros, el extremo de REST puede desviarse de esta construcción sintáctica para tener en cuenta las limitaciones de REST.
- Propiedades y métodos estáticos. Los puntos de conexión de REST se desvían de esta estructura de sintaxis para los URI que representan propiedades y métodos estáticos.
Determinar los puntos de conexión de servicio REST de SharePoint
Para crear un punto de conexión de REST para un recurso de SharePoint, siga estos pasos:
Comience con la referencia del servicio REST:
https://{site_url}/_apiEspecifique el punto de entrada adecuado. Por ejemplo:
https://{site_url}/_api/webNavegue desde el punto de entrada hasta los recursos específicos a los que desea tener acceso. Esto incluye especificar parámetros para extremos que se corresponden con métodos en el modelo de objetos de cliente. Por ejemplo:
https://{site_url}/_api/web/lists/getbytitle('{list_name}')
Hacer referencia al servicio REST de SharePoint en el URI de punto de conexión
Use _api para denotar el servicio REST de SharePoint en los URI de punto de conexión. El servicio REST forma parte del servicio web client.svc. Pero, para simplificar la construcción de URI de REST y acortar la ruta de acceso al URI base de REST, el servicio REST usa _api para eliminar la necesidad de hacer una referencia explícita al servicio web client.svc.
El servicio REST aún reconoce y acepta los URI que hacen referencia al servicio web client.svc. Por ejemplo, puede usar https://{site_url}/_vti_bin/client.svc/web/lists en lugar de https://{site_url}/_api/web/lists. Pero, la convención preferida es usar _api. Las direcciones URL tienen un límite de 256 caracteres; por lo tanto, el uso de _api permite acortar el URI base y dejar más caracteres para usar en la construcción del resto de la dirección URL.
Especificar puntos de entrada para el servicio REST de SharePoint
Los puntos de entrada principales para el servicio REST representan la colección de sitios y el sitio del contexto especificado. De esta manera, estos puntos de entrada corresponden a las propiedades ClientContext.Site y ClientContext.Web en los modelos de objetos de cliente.
Para obtener acceso a una colección de sitios específica, use la siguiente construcción:
https://{site_url}/_api/site
Para obtener acceso a un sitio específico, use la siguiente construcción:
https://{site_url}/_api/web
Además de /site y /web, el servicio REST incluye varios puntos más de acceso que permiten a los desarrolladores navegar a una funcionalidad concreta. En la tabla siguiente se muestran algunos de estos puntos de acceso.
| Área de característica | Punto de acceso |
|---|---|
| Sitio | https://{site_url}/_api/site |
| Web | https://{site_url}/_api/web |
| Perfil de usuario | https://{site_url}/_api/SP.UserProfiles.PeopleManager |
| Búsqueda | https://{site_url}/_api/search |
Navegar a los recursos específicos a los que quiere tener acceso
Desde aquí, construya extremos REST más específicos al "caminar" el modelo de objetos, con el uso de los nombres de las API del modelo de objetos de clientes separados por una barra diagonal (/). En la tabla siguiente se muestran ejemplos de llamadas de modelo de objetos de cliente y el punto de conexión REST equivalente.
| API de modelo de objetos de cliente | Punto de conexión de REST |
|---|---|
| ClientContext.Web.Lists | https://{site_url}/_api/web/lists |
| ClientContext.Web.Lists[guid] | https://{site_url}/_api/web/lists('<guid>') |
| ClientContext.Web.Lists.GetByTitle("Title") | https://{site_url}/_api/web/lists/getbytitle('<Title>') |
Los URI de punto de conexión no distinguen mayúsculas y minúsculas. En la tabla anterior, por ejemplo, use /getbytitle para especificar el equivalente REST del método GetByTitle().
Especificar parámetros en los URI de punto de conexión de REST
SharePoint extiende la especificación OData para permitirle el uso de paréntesis para especificar los parámetros de métodos y valores de índice. Esto impide posibles problemas de desambiguación en los URI que contienen varios parámetros con el mismo nombre. Por ejemplo, los dos URI siguientes contienen parámetros que tienen el mismo nombre:
https://{site_url}/_api/web/lists/getByTitle('Announcements')/fields/getByTitle('Description')
https://{site_url}/_api/web/lists('{list_guid}')/fields/getById('{guid}')
Para especificar varios parámetros, incluya el parámetro como par nombre-valor, y separe los parámetros con comas. Por ejemplo:
https://{site_url}/_api/web/getAvailableWebTemplates(lcid=1033, includeCrossLanguage=true)
La siguiente figura muestra la sintaxis del parámetro REST de SharePoint.
Sintaxis del parámetro REST de SharePoint
Tipos complejos como parámetros para el servicio REST
Algunos métodos en el modelo de objetos de clientes necesitan una gran carga como parámetro. Para que los extremos de REST mantengan la paridad de funciones con sus API de modelos de objetos de clientes correspondientes, los extremos necesitan aceptar un tipo complejo como parámetro. En estos casos, el servicio REST extiende el protocolo OData existente para permitir que estos extremos de REST acepten un solo tipo complejo como parámetro. Esto se aplica a las acciones POST únicamente, y usted tiene que pasar el tipo complejo en formato Atom o formato JSON, según los estándares OData.
Por ejemplo, el método ListCollection.Add acepta un objeto Microsoft.SharePoint.Client.ListCreationInformation como parámetro. Para agregar una lista a un sitio especificado, cree el punto de conexión de REST adecuado de la siguiente manera:
POST https://{site_url}/_api/web/lists/add
Authorization: "Bearer " + accessToken
Accept: "application/json;odata=verbose"
Content-Type: "application/json"
Content-Length: {length of request body as integer}
{ "d" : {
"results": {
"__metadata": {
"type": "SP.ListCreationInformation"
},
"CustomSchemaXml": "…large payload…/",
"Description": "desc",
"DocumentTemplateType": "1",
"TemplateType": "101",
"Title": "Announcements"
}
}
}
Usar alias de parámetros en llamadas de servicio REST
Puede usar la semántica "alias de parámetros" en OData para pasar parámetros a un extremo de REST de SharePoint. En alias de parámetros, el valor de parámetro se identifica con un alias en la llamada de parámetro, y el valor real se especifica en la cadena de consulta del URI. Esto posibilita el uso de más tipos de caracteres y un formato uniforme con el uso de la cadena de consulta.
Por ejemplo, los dos URI de REST siguientes son equivalentes:
Especificar el valor del parámetro directamente:
https://{site_url}/_api/web/applyWebTemplate("STS#0")
Usar un alias de parámetro y especificar el valor del parámetro real en la cadena de consulta del URI:
https://{site_url}/_api/web/applyWebTemplate(title=@template)?@template="STS#0"
Pero, el servicio REST de SharePoint no admite que se pasen tipos complejos a través de alias de parámetros. Por ejemplo, no se admite la siguiente URI, que contiene un tipo complejo en el alias de parámetros:
https://{site_url}/_api/userProfiles/People(7)/GetWorkplace(@address)?@address={"__metadata":{"type: "ODataDemo.Address"},"Street":"NE 228th", "City":"Sammamish","State":"WA","ZipCode":"98074","Country": "USA"}
Sintaxis de alias de parámetros del servicio REST de SharePoint
Especificar diccionarios como valores de parámetros
En el caso de puntos de conexión REST que corresponden a métodos que aceptan diccionarios Dictionary<String, String> como parámetros, pase el diccionario como una serie de pares nombre-valor delimitados por comas en la cadena de consulta.
Sintaxis del servicio REST para parámetros Dictionary
Un Dictionary<String, object> se representa como un objeto multivalor, denominado KeyedPropertyValue, con las siguientes propiedades de cadena:
- Key Clave del objeto multivalor.
- Value Valor del objeto.
- ValueType El tipo de valor del objeto. En el caso de los tipos de valor simples que se asignan a tipos de Entity Data Model (EDM) existentes, el servicio REST devuelve la cadena de tipo EDM adecuada; por ejemplo, "Edm.String". Si no es así, el servicio REST devuelve el tipo de valor devuelto por la función Type.ToString .
Especificar valores de parámetros en la cadena de consulta
Si su URI REST finaliza en una llamada de método, puede usar la sintaxis de cadena de consulta para especificar los valores de parámetros del método. Por ejemplo:
https://{site_url}/_api/web/applyWebTemplate?template="STS#0"
En la ilustración siguiente se muestra la sintaxis del servicio REST para parámetros en la cadena de consulta.
Sintaxis del servicio REST para parámetros en una cadena de consulta
Especificar propiedades y métodos estáticos como identificadores URI de servicio REST
Para construir URI que corresponden a propiedades o métodos estáticos, use el nombre de API correspondiente del modelo de objetos ECMAScript, a partir de la declaración de espacios de nombres y usando la notación de punto. Por ejemplo, SP. Utilities.Utility.getImageUrl(imageName) en el modelo de objetos de cliente ECMAScript tendría el siguiente equivalente REST:
https://{site_url}/_api/SP.Utilities.Utility.getImageUrl('imageName')
Pero solo se puede obtener acceso a las propiedades estáticas directamente, no se permiten como una composición URI más grande. Por ejemplo, se puede permitir obtener acceso directamente al método SP.Utility.AssetsLibrary en REST, de la siguiente manera:
https://{site_url}/_api/SP.Utility.assetsLibrary/id
Pero, no se permite el uso de esa ubicación de recursos como parámetro para un URI más complejo, tal y como se muestra en el siguiente ejemplo:
https://{site_url}/_api/getList(~SP.Utility/assetsLibrary/id)
En la ilustración siguiente se muestra la sintaxis de miembro estático del servicio REST de SharePoint.
Sintaxis de miembro estático del servicio REST de SharePoint
Si quiere seleccionar, filtrar u ordenar los datos solicitados desde un extremo, el servicio REST de SharePoint admite una amplia gama de operadores de cadena de consultas OData. Para obtener más información, vea Usar operaciones de consulta de OData en solicitudes REST de SharePoint.