Introduction to the Data Export API

Статья
04/16/2024

Yammer Data Export will package and export all messages (including previous versions), Files stored in Yammer, topics, users, and groups. Data will be exported into a zip file containing .csv files for messages (including previous versions) and additional archives containing Files.

Perform a one-time export simply by specifying the starting date from which you would like to export and the end date to which you would like to export. Alternatively, you can also set up recurring exports on a daily or weekly basis per your business needs.

Highlights

Comprehensive Data Export: Export all the data on your network, including messages (including previous versions), Files, topics, users, and groups. Note: We recommend downloading data with files by using a one-day range, to reduce the likelihood of errors caused by an unreliable data connection. If there are a lot of files on the specified day, we recommend exporting by using a one-hour range.
Data Export API: Utilize the Data Export API to set up and customize automatic, recurring exports for your network. The API provides more control, flexibility, and customization for IT admins.
Simplified One-Time Exports: Simply specify a starting date to have all of your network data from that starting point exported.
For the network on which the external group "lives", export all content in that group.
For the external user that is a group member, VAs only receive threads that the external user explicitly participated in (posted a message to). If there is a message in the group that the user did not participate in, it will not be available in the data export.

Network Data Exports can also be performed by visiting Yammer Network Admin > Content and Security > Export Data.

Authorization

The Data Export API can only be used by Yammer Verified Administrators. An OAuth 2 access token belonging to a verified admin must be used and set as a “Bearer” token in the “Authorization” request header.

The Data Export API supports using both the legacy Yammer OAuth 2 token and Azure Active Directory tokens acquired using MSAL. Learn more about supported authentication types here

GET /api/v1/messages/following.json HTTP/1.1 
Host: www.yammer.com 
Authorization: Bearer abcDefGhi

For more detail on the “Bearer” token refer to: http://tools.ietf.org/html/draft-ietf-oauth-v2-bearer-23

If the access token expires, or the user de-authorizes your app, the API request will return an HTTP 401 with the following error in the body of the response.

{
  "response": {
    "message": "Token not found.",
    "code": 16,
    "stat": "fail"
  }
}

How this API works

This API is synchronous - an HTTP GET request is made to the API and content is returned in the requested format.

Example Queries

Export all data since February 9, 2020:

https://www.yammer.com/api/v1/export?since=2020-02-09T00:00:00+00:00

Export all data since February 9, 2020, and until March 10th, 2021:

https://www.yammer.com/api/v1/export?since=2020-02-09T00:00:00+00:00&until=2021-03-10T00:00:00+00:00

Export all data since February 9, 2020 but exclude file attachments:

https://www.yammer.com/api/v1/export?since=2020-02-09T00:00:00+00:00&include=csv

Export message data since February 9, 2020, and exclude file attachments:

https://www.yammer.com/api/v1/export?since=2020-02-9T00:00:00+00:00&model=Message&include=csv

Query Parameters

model: Indicates which models to be exported. All available models will be exported if no model is specified. Multiple models may be specified with multiple parameters with the 'model' name. Available models include:
- User
- Group
- Message
- MessageVersion
- Topic
- Tags
- UploadedFileVersion
- AMAs
- AnswerVote
- Campaigns
- Leader
- LikedMessage
- Sentie
- Topic
- VivaTopic
- VivaTopicApplication
- VivaTopicCurationStateLog
since: (Required parameter) - Indicates the start date of the export. All exported changes will have occurred on or after this date. Must be encoded as an ISO-8601 date.
- until: Indicates the end date of the export. All exported changes will have occurred on or before this date (Note: Since export is looking at the until date at 00:00 GMT, use until today+1 if you cannot see the models created on the day of the export). If you're planning on a very large export, use "until" to break up the export into manageable pieces (data exports of a very large size may fail). Must be encoded as an ISO- 8601 date. If this value is not provided, until defaults to the current date.
- include: Defines whether to include file attachments or not. Options are ‘csv’ (no attachments) or ‘all’ (include attachments).
- network: Which network(s) one wishes to export. Must be accessible using the provided OAuth bearer token. i.e. the network associated with the token, or associated external networks.
- include_ens: If ‘true’, automatically include all external networks associated with the network associated with the OAuth bearer token.

Ensure that the parameters are correctly URL encoded before executing the request to the Data Export API. Some tools will handle this automatically, but you should check this when troubleshooting.

API Response

The response is an application/zip (ZIP file) payload encapsulating the contents of the data export. Internally, the ZIP file will contain the following files and directories for a complete export:

csv files for all or specifically requested models via query parameters
log.txt
request.txt

Messages.csv vs MessageVersions.csv

Message export follows these two criteria:

Exports only versions that fall in the time search range
If a message is the latest version, it will appear in both Messages.csv and MessageVersions.csv.

MessageVersions.csv

This means, if the latest version of a message is in the time range, it will be exported in both Messages.csv and MessageVersions.csv; any older version within the time range will only be exported in MessageVersions.csv.

Response CSV Files Contents

The following fields are exported in CSVs in the Data Export API.

File	Content
log.txt	Summary of the export
request.txt	The parameters of the export
Admins.csv	A list of current admins, their email addresses, and whether they are a verified admin or a network admin. The CSV file contains the following columns: id name email verified
AMAs.csv	The CSV file contains the following columns: id title description created_at updated_at meeting_state tenant_id added_by partner_id start_time end_time meeting_state admission_type qna_app_enabled replies_enabled moderation_enabled is_thread_upvote_enabled access_category cs_subscription_status presenter_option join_link artifact_service_enabled qna_app_enabled is_anonymous_posting_enabled auto_admitted_policy created_by_type calendar_id participants_data
AnswerVotes.csv	The CSV file contains the following columns: id network_id voter_id message_id thread_id created_at updated_at
Campaigns	The CSV file contains the following columns: id name api_url description hashtags state official created_at creator_id default_cover_image_url_template cover_image_url_template permalink
Files.csv	For any file added or modified during this date range from Yammer, lists the Yammer ID, type of file, name, description, and path to the file, along with metadata including the group it was posted in. The storage_path column shows whether the file is stored in Yammer or SharePoint. Files.csv does not contain the actual files. Files that are stored in Yammer are exported in their native format to the Files folder of the zip file. Files that are stored in SharePoint are not exported. Files.csv contains the following columns: id file_id name description uploader_id uploader_type group_id group_name reverted_to_id deleted_by_user_id in_private_group in_private_conversation file_api_url download_url path uploaded_at deleted_at original_network storage_type scope_id scope_type
Groups.csv	For any group created or modified during the specified date range, lists the Yammer ID, name, description, privacy status, whether the group is internal or external, link to the group, who created the group, creation date, and updated date. The CSV file contains the following columns: id name description private moderated api_url created_by_id created_by_type created_at updated_at deleted external office_group_id group_tags group_custom_cover_image
LikedMessages.csv	The CSV file contains the following columns: id replied_to_id parent_id thread_id conversation_id group_id group_name participants in_private_group in_private_conversation sender_id sender_type sender_name sender_email body api_url attachments deleted_by_id deleted_by_type created_at deleted_at title html_body message_type gdpr_delete_url reaction scope_id scope_type is_supplemental_reply
Messages.csv	Lists the messages sent or modified during the selected time period. The CSV file contains the following columns: id replied_to_id parent_id thread_id conversation_id group_id group_name participants in_private_group in_private_conversation sender_id sender_type sender_name sender_email body delegate_id api_url attachments* deleted_by_id deleted_by_type created_at deleted_at title html_body message_type gdpr_delete_url scope_id scope_type is_supplemental_reply is_draft: boolean value to indicate if the message is a draft (not yet published for other users to see) intelligent_importer_extraction_id: Extraction id associated with messages which were generated via Intelligent Importer. This id does not correspond to any other exported model, but can be used to correlate messages that were generated together. is_ai_generated: boolean value to indicate if a message was generated by AI. If a message was generated as a draft, such as with Intelligent Importer, it is only considered AI generated until it is published. Once an AI-generated message is posted, this flag is reset and the message in export appears like any other message posted by a user. intelligent_importer_file_id: Id of the file used by Intelligent Importer to extract a message. * Within attachments this OGO information is exported: id, url, title, description.
MessageThreads.csv	The CSV file contains the following columns: id files external_participants updated_at original_network is_announcement is_reply_disabled
MessageThreadOutbound.csv	Includes IDs of external participants in outbound messages. The CSV file contains the following columns: id files external_participants updated_at is_announcement is_reply_disabled
MessageVersions.csv	Includes IDs and modification information for messages that have been edited. The CSV file contains the following columns: id replied_to_id parent_id thread_id conversation_id group_id group_name participants in_private_group in_private_conversation sender_id sender_type sender_name sender_email body delegate_id api_url attachments deleted_by_id deleted_by_type created_at deleted_at title html_body message_type gdpr_delete_url scope_id scope_type is_supplemental_reply is_draft: boolean value to indicate if the message is a draft (not yet published for other users to see) intelligent_importer_extraction_id: Extraction id associated with messages which were generated via Intelligent Importer. This id does not correspond to any other exported model, but can be used to correlate messages that were generated together. is_ai_generated: boolean value to indicate if a message was generated by AI. If a message was generated as a draft, such as with Intelligent Importer, it is only considered AI generated until it is published. Once an AI-generated message is posted, this flag is reset and the message in export appears like any other message posted by a user. intelligent_importer_file_id: Id of the file used by Intelligent Importer to extract a message.
Networks.csv	Lists your home network and all external networks included in the export. The CSV file contains the following columns: id permalink name url paid created_at moderated usage_policy number_of_users secure_browser_token
Sentie.csv	The CSV file contains the following columns: user_id sentiment_score sentiment_opinions text_sentiment leaders creator_id thread_id
Topics.csv	Lists creation information and a link for any article created during the specified date range. The CSV file contains the following columns: id name created_by created_at api_url description
UserGroupRecommendationActions.csv	The CSV file contains the following columns: id user_prompt_view_times group_recommendation_dismiss_times
Users.csv	Lists data for all users who joined, or were deleted or suspended during the specified date range. The CSV file contains the following columns: id name email job_title location department api_url deleted_by_id deleted_by_type joined_at deleted_at suspended_by_id suspended_by_type suspended_at guid state office_user_id user_cover_image_url sash_campaign_id
VivaEngageLeaders.csv	The CSV file contains the following columns: leader_id leader_created_at audience_name audience_created_at audience_created_by audience_updated_at audience_updated_by size audience_group_ids entire_org
VivaTopicApplications.csv	For any topic applied to a post, lists information about each application for the date range specified (if any). The CSV file contains the following columns: cortex_topic_id applicant_id target_id group_id target_type deleted is_topic_curated created_at updated_at topic_name
VivaTopicCurationStateLogs.csv	Applies to only Answers in Viva, contains the curation state logs for topics that have been featured. cortex_topic_id can be used in conjunction with the content of VivaTopics.csv to retrieve other information relevant to the topic. The CSV file contains the following columns: cortex_topic_id topic_curation_state_update acting_user_id committed_to_km_at created_at updated_at
VivaTopics.csv	Any topic created or updated is displayed for the date range specified (if any). The id refers to the Viva Topic identifier.The api_url is the URL used to obtain the topic metadata.The CSV file contains the following columns: id name created_by created_at api_url description legacy_id merged_ids short_description topic_curation_state

Potential Failure

If there are errors exporting any data, the data export will be a partial export. In this case, the log.txt will contain details of what failed to export. The best way to avoid partial failures is to export smaller timeframes at a time. Large data exports are more likely to fail.

A Sample Code using the API in Unix and Windows PowerShell is provided here. This Sample Code is provided for the purpose of illustration only and is not intended to be used as-is in a production environment.

Поделиться через