Procedimientos recomendados para trabajar con la API de Excel

  • Artículo

En este artículo se proporcionan recomendaciones para trabajar con las API de Excel en Microsoft Graph.

Administrar sesiones de la manera más eficaz

Si tiene más de una llamada que realizar en un período de tiempo determinado, se recomienda crear una sesión y pasar el identificador de sesión con cada solicitud. Para representar la sesión en la API, utilice el encabezado workbook-session-id: {session-id}. Al hacerlo, puede usar las API de Excel de la manera más eficaz.

En el ejemplo siguiente se muestra cómo agregar un nuevo número a una tabla y, a continuación, buscar un registro en un libro mediante este enfoque.

Paso 1: Crear una sesión

Solicitud

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/createSession
Content-type: application/json

{
  "persistChanges": true
}

Respuesta

A continuación se muestra una respuesta correcta.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "id-value",
  "persistChanges": true
}

Paso 2: Agregar una nueva fila a la tabla

Solicitud

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/tables/{id|name}/rows/add
Content-type: application/json
workbook-session-id: {session-id}

{
  "values": [[“east”, “pear”, 4]]
}

Respuesta

HTTP/1.1 200 OK
Content-type: application/json

{
  "index": 6,
  "values": [[“east”, “pear”, 4]]
}

Paso 3: Buscar un valor en la tabla actualizada

Solicitud

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/functions/vlookup
Content-type: application/json
workbook-session-id: {session-id}

{
    "lookupValue":"pear",
    "tableArray":{"Address":"Sheet1!B2:C7"},
    "colIndexNum":2,
    "rangeLookup":false
}

Respuesta

HTTP code: 200 OK
content-type: application/json

{
    "value": 5
}

Paso 4: Cerrar la sesión una vez completadas todas las solicitudes

Solicitud

POST https://graph.microsoft.com/v1.0/me/drive/items/{id}/workbook/closeSession
Content-type: application/json
workbook-session-id: {session-id}

{
}

Respuesta

HTTP/1.1 204 No Content

Para obtener más información, vea Crear sesión y Cerrar sesión.

Trabajar con API que tardan mucho tiempo en completarse

Es posible que observe que algunas operaciones tardan un tiempo indeterminado en completarse; por ejemplo, abrir un libro grande. Es fácil alcanzar el tiempo de espera mientras se espera la respuesta a estas solicitudes. Para resolver este problema, se proporciona el patrón de operación de ejecución prolongada. Cuando se usa este patrón, no es necesario preocuparse por el tiempo de espera de la solicitud.

Actualmente, la API de Excel de creación de sesión en Microsoft Graph tiene habilitado el patrón de operación de ejecución prolongada. Este patrón implica los pasos siguientes:

  1. Agregue un Prefer: respond-async encabezado a la solicitud para indicar que se trata de una operación de larga duración al crear una sesión.
  2. Una operación de ejecución prolongada devuelve una 202 Accepted respuesta junto con un encabezado Location para recuperar el estado de la operación. Si la creación de la sesión se completa en varios segundos, devuelve una respuesta de sesión de creación regular en lugar de usar el patrón de operación de ejecución prolongada.
  3. Con la 202 Accepted respuesta, puede recuperar el estado de la operación en la ubicación especificada. Los valores de estado de la operación son notStarted, running, succeededy failed.
  4. Una vez completada la operación, puede obtener el resultado de la creación de la sesión a través de la dirección URL especificada en la respuesta correcta.

En el ejemplo siguiente se crea una sesión con el patrón de operación de ejecución prolongada.

Solicitud inicial para crear sesión

Solicitud

POST https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/createSession
Prefer: respond-async
Content-type: application/json
{
    "persistChanges": true
}

Respuesta

El patrón de operación de ejecución prolongada devuelve una 202 Accepted respuesta similar a la siguiente.

HTTP/1.1 202 Accepted
Location: https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
Content-type: application/json

{
}

En algunos casos, si la creación se realiza correctamente en cuestión de segundos, no escribirá el patrón de operación de ejecución prolongada; en su lugar, devuelve como una sesión de creación normal y la solicitud correcta devolverá una 201 Created respuesta.

HTTP/1.1 201 Created
Content-type: application/json

{
  "id": "id-value",
  "persistChanges": true
}

En el ejemplo siguiente se muestra la respuesta cuando se produce un error en la solicitud.

Nota: Se puede acortar el objeto de respuesta que se muestra aquí para mejorar la legibilidad.

HTTP/1.1 500 Internal Server Error
Content-type: application/json

{
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": "internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

Estado de sondeo de la sesión de creación de ejecución prolongada

Con el patrón de operación de ejecución prolongada, puede obtener el estado de creación en la ubicación especificada mediante la siguiente solicitud. El intervalo sugerido para sondear el estado es de aproximadamente 30 segundos. El intervalo máximo no debe ser superior a 4 minutos.

Solicitud

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/operations/{operation-id}
{
}

Respuesta

A continuación se muestra la respuesta cuando la operación tiene un estado de running.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "running"
}

A continuación se muestra la respuesta cuando el estado de la operación es succeeded.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": {operation-id},
    "status": "succeeded",
    "resourceLocation": "https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
}

A continuación se muestra la respuesta cuando el estado de la operación es failed.

HTTP/1.1 200 OK
Content-type: application/json

{
  "id": {operation-id},
  "status": "failed",
  "error":{
    "code": "internalServerError",
    "message": "An internal server error occurred while processing the request.",
    "innerError": {
      "code": ""internalServerErrorUncategorized",
      "message": "An unspecified error has occurred.",
      "innerError": {
        "code": "GenericFileOpenError",
        "message": "The workbook cannot be opened."
      }
    }
  }
}

Para obtener más información sobre los errores, vea Códigos de error y mensajes.

Adquisición de información de sesión

Solicitud

Con un estado de succeeded, puede obtener la información de sesión creada a través de resourceLocation una solicitud similar a la siguiente.

GET https://graph.microsoft.com/v1.0/me/drive/items/{drive-item-id}/workbook/sessionInfoResource(key='{key}')
{
}

Respuesta

A continuación se muestra la respuesta.

HTTP/1.1 200 OK
Content-type: application/json

{
    "id": "id-value",
    "persistChanges": true
}

Nota:

Adquirir información de sesión depende de la solicitud inicial. No es necesario adquirir el resultado si la solicitud inicial no devuelve un cuerpo de respuesta.

Reducción de errores de limitación

Las API de Excel en Microsoft Graph afectan al uso de recursos de varios servicios de dependencia. El impacto puede variar entre distintas solicitudes: por ejemplo, puede esperar que actualizar una cadena corta en una sola celda de un libro pequeño consuma menos recursos que agregar una tabla grande con fórmulas complejas a un libro grande.

Incluso con la misma API, los parámetros y los libros de destino pueden introducir diferencias significativas. Por lo tanto, la limitación de la API de Excel no se define con números de límite simples y universales, ya que darían lugar a límites más restrictivos. Los siguientes procedimientos recomendados le ayudarán a completar las tareas más rápidamente con menos errores de limitación.

encabezado Retry-After

En muchos casos, una respuesta de limitación incluye un Retry-After encabezado. Respetar el valor del encabezado y retrasar solicitudes similares ayudaría al cliente a recuperarse de la limitación. Para obtener más información sobre cómo controlar las respuestas de error de las API de Excel en Microsoft Graph, vea Control de errores para las API de Excel en Microsoft Graph.

Limitación y simultaneidad

Otro factor relacionado con la limitación es la simultaneidad de solicitudes. No se recomienda aumentar la simultaneidad al usar las API de Excel (por ejemplo, paralelizar las solicitudes con el mismo libro), especialmente para las solicitudes de escritura. En su lugar, a menos que haya una preocupación específica, como una sobrecarga de red significativa en comparación con un tiempo de ejecución de solicitud muy corto, se recomienda el uso secuencial en el caso más común: para cada libro, solo envíe la siguiente solicitud después de recibir una respuesta correcta a la solicitud actual.

Las solicitudes de escritura simultáneas al mismo libro no se suelen ejecutar en paralelo (aunque en algunos casos lo hacen); en su lugar, suelen ser la causa de la limitación, el tiempo de espera (cuando las solicitudes se ponen en cola en los servidores), el conflicto de combinación (cuando hay sesiones simultáneas implicadas) y otros tipos de errores. También complican el control de errores; por ejemplo, cuando recibe una respuesta de error, no hay ninguna manera de confirmar el estado de otras solicitudes pendientes, lo que dificulta determinar o recuperar el estado del libro.

Contenido relacionado