Export Files from Yammer's cloud storage.

  • Articolo

Introduction

The Yammer Files Export API lets Verified Administrators archive and export files in Yammer storage in an asynchronous manner. This API is intended to augment the existing Data Export API when there is a significant volume of files to be exported. In combination, these APIs allow networks with very large volumes of content to perform a complete export. The existing Data Export API should be the starting point for all developers.

You can perform a Files export by specifying the start and end date to which you would like to export. Data is exported into a Zip file containing a .csv file with information about the export and additional archives with files exported from your Yammer network.

The Files Export API is scoped only to asynchronously exporting Files stored in Yammer cloud storage in their native format. Files stored in SharePoint file storage will not be included in the Zip file, but the download_url in Files.csv will work if the user has access to those Files in SharePoint.

Use the Yammer data export API to export all other content from your Yammer network, such as Messages, Users, Groups and Topics. The model parameters can be adapted to the content types that need to be exported.

How this API works

The existing Yammer APIs are synchronous. An HTTP request is made to the API and content is returned in the requested format. Data export payloads are much larger than that of REST endpoints which introduces challenges when large volumes of files are encountered.

The Yammer Files Export API is asynchronous. An initial request is made to the API and an export request ID is returned. The data export begins processing on the backend. Further requests are made using the request ID to check on progress. Once the request has processed another URL to the final export download is provided. This is a simple HTTP download compared to the streaming approach used by the Data Export API.

Authorization

Only Yammer Verified Admins are authorized to make data export requests. The access token must be set as a “Bearer” token in the “Authorization” request header.

Authorization: Bearer [BEARER_TOKEN]

For more details on “Bearer” token refer [here].(For more details on “Bearer” token refer: developer.yammer.com/docs/api-requests) If the Bearer token has expired, then the API will return an HTTP 401 with the following error in the body of the response.

{
  “response”: {
  “message”: {Credentials are required to access this resource.”,
  “code”: 16,
  “stat”: “fail”
    }
 }

Creating a request to export files

The following example demonstrates sending a POST request to export files.

POST yammer.com/api/v1/export/requests?since=2019-02-09T00:00:00&until=2019-03-10T00:00:00

Query parameters

  • since: ISO-8601 encoded date string
  • until: ISO-8601 encoded date string (optional)
  • network: Which network(s) to export, must be accessible with OAuth bearer token
  • include_ens: If ‘true’, automatically include all external networks associated with the OAuth bearer token

Success response

A successful response will return a “user_request_id” GUID with which you can check the status of your Files export.

CODE: 200 OK
CONTENT: 
{“user_request_id”:”5e5716d6-2eb0-43d1-8782-fc9094058547”}

Error response

CODE: 400 BAD REQUEST
CONTENT: 
“Only one request can be in progress for one admin at a time. Existing Request Id: 5e5716d6-2eb0-43d1-8782-fc9094058547”

Check status of your data export

You can check the status of your Files export with your “User request ID”.

GET yammer.com/api/v1/export/requests/{user_request_id}

API responses

The Yammer Files Export API returns the following responses.

IN PROGRESS

This status indicates that your Yammer Files are being processed for export. Please check the status again to see if your request is complete with your user request id.

CODE: 200 OK
CONTENT:
{
  “user_request_id”: “5e5716d6-2eb0-43d1-8782-fc9094058547”,
  “status”       : “IN PROGRESS”
  “expiry_time”    : “”
  “data”       :[]
}

COMPLETE

A successful response will return a status of complete, with two URLs, first URL containing files from the export, and a second URL containing a CSV with metadata regarding the downloaded files. The download URL automatically expires in one week week as indicated in the expiry time. Do not share the download URLs with individuals who shouldn't have access to the data.

CODE: 200 OK
CONTENT:
{
  “user_request_id”: “5e5716d6-2eb0-43d1-8782-fc9094058547”,
  “status”       : “COMPLETE”
  “expiry_time”    : “2019-02-09T00:00:00:00+00:00”
  “data”       :[

"https://dataexport-s0.assets-yammer.com/container/files.zip?st=2019-01-29T07%3A36%3A46Z&se=2019-01-30T07%3A36%3A46Z&sp=r&sv=2018-03-28&sr=b&sig=test”
]
}

EXPIRED

This status indicates that the URL to download Files from Yammer has expired. Download URLs automatically expire one week after they are issued. Please create a new request to export files from Yammer.

CODE: 200 OK
CONTENT:
{
  “user_request_id”: “5e5716d6-2eb0-43d1-8782-fc9094058547”,
  “status”       : “EXPIRED”
  “expiry_time”    : “2019-02-09T00:00:00+00:00”
  “data”       :[]
}

404 NOT FOUND

This code is generated when there is no data export request available for the “user_request_id” that was provided.

CODE: 404 NOT FOUND
CONTENT: “No export request was found for the request_id: {user_request_id}”

Expiring the Data Export URL

After a Verified Admin has completed downloading the files, it is recommended that the files data export URL is expired. The expiration process disables the URL and files cannot be downloaded.

Query

PUT yammer.com/api/v1/export/requests/{user_request_id}?state=Expired

Query parameters

  • State = Expired

200 OK Success Response

CODE: 200 OK
CONTENT: "Expiration process has successfully initiated. Data URLs will soon be disabled"

Error Responses

401 UNAUTHORIZED

CODE: 401 UNAUTHORIZED
CONTENT: "Updating to a state other than 'Expired' is unauthorized"

400 BAD REQUEST

CODE: 400 BAD REQUEST
CONTENT: "Export with given {user_request_id} has already been expired or failed"

404 NOT FOUND

CODE: 404 NOT FOUND
CONTENT: "No export request was found for the request_id: {user_request_id}"