导入事件

从服务器发送一批活动到Mixpanel。

请求格式

每个请求都会将一批事件摄入Mixpanel。我们最多接受2000年的事件和2MB未压缩的每个请求。事件是请求主体的一部分。我们支持内容类型application/jsonor应用程序/X-NDJSON：

[{{“ event”：“ cignup”，“ properties”：{“ time”：1618716477000，“ distract_id”：“ 91304156-CAFC-4673-A237-6237-623D1129C801”，“-95b84f09b9e4“，”由“：“ friend”，“ url”：“ www.jy710.com/signup”}}}}}，{“ event”：“ pasking”，“ properties”：{“ time”：1618716477000，“ dimption” dimpply_id dimption_id“：“ 91304156-CAFC-4673-A237-623D1129C801”，“” $ INSERT_ID：“ 935D87B1-00CD-41B7-BE34-BE34-B94-B98D98DDDD08B42

{"event": "Signup", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4","Referred by": "Friend","URL": "www.jy710.com/signup"}} {"event": "Purchase", "properties": {"time": 1618716477000,"distinct_id": "91304156-cafc-4673-a237-623d1129c801","$insert_id": "935d87b1-00cd-41b7-be34-b9d98dd08b42","Item": "Coffee", "Amount": 5.0}}

We also supportContent-Encoding: gzip减少网络出口。

Authentication

/import requires an Owner or Admin服务帐户。project_id, service account username and service account password are required to authenticate a request.

Note: /import also supportsProject Secretfor legacy reasons. If you do not specify project_id, we will use secret auth.

验证

/导入验证提供的事件并返回400状态代码，如果anyof the events fail validation with details of the error. If some events pass validation and others fail, we will ingest the events that pass validation. When you encounter a 400 error in production, simply log the JSON response, as it will contain the$insert_id无效事件的s，可用于调试。

高级要求

• Each event must be properly formatted JSON.
• Each event must contain an event name, time, distinct_id, and $insert_id. These are used to deduplicate events, so that this endpoint can be safely retried.
• Each event must be smaller than 1MB of uncompressed JSON.
• 每个事件必须具有不到255个属性。
• All nested object properties must have fewer than 255 keys and max nesting depth is 3.
• 所有数组属性都必须少于255个元素。

Example of an event

{“ event”：“注册”，“属性”：{“ time”：1618716477000，“ distract_id”：“ 91304156-CAFC-4673-A237-6237-623D1129C801”，“-95b84f09b9e4", "ip": "136.24.0.114", "Referred by": "Friend", "URL": "www.jy710.com/signup", } }

event

这是事件的名称。如果您要从数据仓库中加载数据，我们建议将表名称作为事件的名称。

我们建议将唯一事件名称的数量保持相对较小，并使用属性用于事件附加的任何可变上下文。例如，我们建议您建议跟踪一个称为“注册”的事件，并拥有具有“付费”帐户类型“付费”或“免费”的事件，而不是跟踪名称“付费注册”和“免费注册”的事件。

properties

这是代表事件的所有属性的JSON对象。如果您要从数据仓库中加载数据，我们建议使用列名作为属性名称。

properties.time

The time at which the event occurred, in seconds or milliseconds since epoch. We require a value for time. We will reject events with time values that are before 1971-01-01 or more than 1 hour in the future as measured on our servers.

properties.distinct_id

distinct_id identifies the user who performed the event. distinct_id must be specified on every event, as it is crucial for Mixpanel to perform behavioral analysis (unique users, funnels, retention, cohorts) correctly and efficiently.

如果事件与任何用户没有关联，请将Distract_id设置为空字符串。所有行为分析将排除具有空白的事件。

为了防止意外实施错误，我们不允许以下值对Distination_ID：

- 00000000-0000-0000-0000-000000000000 - anon - anonymous - nil - none - null - n/a - na - undefined - unknown -  - 0 - -1 - true - false - [] - {}

属性。$ insert_id

We require that $insert_id be specified on every event. $insert_id provides a unique identifier for the event, which we use for deduplication. Events with identical values for (event, time, distinct_id, $insert_id) are considered duplicates and only one of them will be surfaced in queries.

$ insert_ids必须≤36个字节，并且仅包含字母数字字符或“ - ”。我们还从上面提供的Distine_ID的无效ID列表中不允许$ insert_id的任何值。

验证错误的示例

{ "code": 400, "error": "some data points in the request failed validation", "failed_records": [ { "index": 0, "$insert_id": "8a66058c-a56d-4ef6-8123-28b7c9f7e82f", "field": "properties.time", "message": "properties.time' is invalid: must be specified as seconds since epoch" }, { "index": 3, "$insert_id": "29fc2962-6d9c-455d-95ad-95b84f09b9e4", "field": "properties.utm_source", "message": "properties.utm_source is invalid: string should be valid utf8" }, ], "num_records_imported": 23, "status": "Bad Request" }

当批处理中的任何单个事件都没有通过验证，我们将返回400个状态代码和看起来像以上的响应。

failed_recordsincludes one row for each of the failed events, with details about the error we found. If some of the rows passed validation, we will ingest them and return their count innum_records_imported。

GeoIP Enrichment

如果您提供财产ip使用IP地址，MixPanel将自动进行GeoIP查找并替换ipproperty with geographic properties (City, Country, Region). These properties can be used in our UI to segment events geographically.

这是充实前后事件的一个例子：

{“ event”：“注册”，“属性”：{“ time”：1618716477000，“ distract_id”：“ 91304156-CAFC-4673-A237-6237-623D1129C801”，“-95b84f09b9e4", "ip": "136.24.0.114", "Referred by": "Friend", "URL": "www.jy710.com/signup", } }

{“ event”：“注册”，“属性”：{“ time”：1618716477000，“ distract_id”：“ 91304156-CAFC-4673-A237-6237-623D1129C801”，“-95b84f09b9e4“，”由“：”：“ friend”，“ url”：“ www.jy710.com/signup”，“ $ city”：“ san Francisco”，“ $ region”，“ california”：“ california”，“ mp_country_code”：“}}}

Rate Limits

To ensure real-time ingestion and quality-of-service, we have a rate limit of 2GB of uncompressed JSON/minute or ~30k events per second, measured on a rolling 1 minute basis.

我们建议以下有关将数据大规模发送到我们的API时：

• 与并发客户端尽快发送数据，直到服务器返回429。我们看到了最佳结果，每批次的10-20个并发客户端发送2K事件。
• 当您看到429s时，请使用exponential backoff with jitter战略。我们建议从2s的退缩开始，然后将后退加倍，直到60年代，以1-5秒的抖动。
• 我们建议GZIP压缩并使用Content-Encoding: gzipto reduce network egress and transfer time.
• In the rare event that our API returns a 502 or 503 status code, we recommend employing the same exponential backoff strategy as with 429s.
• Please do not retry validation errors (400 status code), as they will consistently fail and count toward the rate limit.

如果您是企业客户，并且需要更高的限制1次回填，请与您的Project_ID和用例联系您的销售代表。

Common Issues

$insert_id is required on all events. This makes it safe to retry /import requests. If your events don't already have a unique ID (eg: a UUID/GUID), we recommend computing a hash of some set of properties that make the event semantically unique (eg: distinct_id + timestamp + some other property) and using the first 36 characters of that hash as the $insert_id.

We truncate all strings down to 255 characters. Here's what we recommend for the various cases in which this typically happens:

• URLs: We recommend parsing the URL and tracking its individual components (host, path, url params) as properties. This is more useful in analysis, as you can segment events by hostname or a particular URL parameter.
• JSON编码的字符串：有时长字符串可能是编码为字符串的JSON对象。我们建议对JSON进行解析，并将其放入属性中以发送活动。同样，这在分析中更有用，因为您可以通过JSON中的任何键过滤或分解。
• Free text / user generated content: Some long fields may include full-text (eg: a search term or a comment). If this property isn't useful for analysis, we recommend excluding it from tracking to Mixpanel to avoid accidentally sending over any PII.

向导

See our Cloud Ingestion guides for example usage of this API to integrate withGoogle Pub/Sub，，，，亚马逊S3， 要么Google Cloud Storage。