streaming

Documentation

Overview

Package streaming implements Streaming API.

Note that Streaming API is available in beta testing mode. This could be changes and amended.

Streaming API transfers data via the WebSocket protocol. You create a stream, add necessary rules and receive data matching the rules.

With Streaming API you can receive not more than 1% of all public data matching the rules set. To get access to the extended Streaming API version that includes 100% data please write to support https://vk.com/support?act=new_api

VK documentation https://vk.com/dev/streaming_api_docs

Initialization

This can be used with a service token.

vk := api.NewVK(serviceToken)
s, err := streaming.NewStreaming(vk)

You can change client for http and websocket:

s.Client = ... // default http.DefaultClient,
s.Dialer = ... // default websocket.DefaultDialer,

Rules Format

A rule is a set of keywords. If they present in an object text, that object gets into the stream.

- If the words are listed without double quotes, the search will be simplified (all word forms, case insensitive).

- To search an exact match (all word forms, case sensitive etc.) each word should be put inside double quotes.

- Use minus (-) to exclude text with this keyword.

Each rule has a ‘’’value’’’, the rule’s content and a ‘’’tag’’’. With each object you receive a list of its tags to figure out what rules does it fit.

Limitations

- the maximum number of rules — 300;

- the maximum number of keywords in a rule — 100;

- the maximum length of a rule (value) in bytes — 4096;

Methods List

You need the following methods to work with Streaming API:

s.GetRules() //  gets current rules from a stream
s.AddRule(tag, value) // adds a new rule to a stream
s.DeleteRule(tag) // removes a rule from a stream
s.UpdateRules(rules) // removes all rules and adds a new rule to a stream

Getting Stream

Handler for event:

s.OnEvent(func(e streaming.Event) {
	...
}))

For start streaming:

if err := s.Run(); err != nil {
	...
}

For stop streaming:

s.Shutdown()

Index

• type Action
• type Author
• type Error
  • func (e Error) Error() string
  • func (e Error) Is(target error) bool
• type ErrorType
  • func (e ErrorType) Error() string
• type Event
• type EventType
• type Rule
• type Streaming
  • func NewStreaming(vk *api.VK) (*Streaming, error)
  • func (s *Streaming) AddRule(tag, value string) error
  • func (s *Streaming) DeleteRule(tag string) error
  • func (s *Streaming) GetRules() ([]Rule, error)
  • func (s *Streaming) OnEvent(f func(Event))
  • func (s *Streaming) Run() error
  • func (s *Streaming) Shutdown()
  • func (s *Streaming) UpdateRules(rules []Rule) error

Types

type Action

type Action string

Action with the object.

const (
	New     Action = "new"     // new object has been created
	Update  Action = "update"  // object has been updated
	Delete  Action = "delete"  // object has been deleted
	Restore Action = "restore" // object has been restored
)

Possible values.

type Author

type Author struct {
	ID        int    `json:"id"`         // author ID
	AuthorURL string `json:"author_url"` // URL of the author's page
	// ID of the author of the original post (for EventType = Share)
	SharedPostAuthorID int `json:"shared_post_author_id,omitempty"`
	// URL of the original post's author's page  (for EventType = Share)
	SharedPostAuthorURL string          `json:"shared_post_author_url,omitempty"`
	Platform            object.Platform `json:"platform"` // Platform used by author
}

Author struct.

type Error

type Error struct {
	Code    ErrorType `json:"error_code"` // error code
	Message string    `json:"message"`    // error message
}

Error description.

func (Error) Error

func (e Error) Error() string

Error returns the message of a Error.

func (Error) Is

func (e Error) Is(target error) bool

Is unwraps its first argument sequentially looking for an error that matches the second.

type ErrorType

type ErrorType int

ErrorType is the type of an error.

const (
	ErrNoType ErrorType = 0 // NoType error
	// Settings for updating the connection to WebSocket are incorrectly
	// transmitted.
	ErrUpgradeWebsocket             ErrorType = 1000
	ErrUnsupportedHTTP              ErrorType = 1001 // Unsupported HTTP method
	ErrContentType                  ErrorType = 1002 // “Content-type” key is absent or invalid
	ErrMissingKey                   ErrorType = 1003 // "key" parameter is absent
	ErrBadKey                       ErrorType = 1004 // "key" parameter is invalid
	ErrBadStreamID                  ErrorType = 1005 // "stream_id" parameter is invalid
	ErrConnectionAlreadyEstablished ErrorType = 1006 // Such connection has been established already
	ErrInvalidJSON                  ErrorType = 2000 // Invalid JSON
	ErrTagAlreadyExist              ErrorType = 2001 // The rule this such tag has been added already
	ErrTagNotExist                  ErrorType = 2002 // The this such tag is absent
	ErrInvalidRule                  ErrorType = 2003 // Invalid rule
	ErrTooManyFilters               ErrorType = 2004 // Too many filters in one rule
	ErrUnbalancedQuotes             ErrorType = 2005 // Unbalanced quotes
	ErrTooManyRules                 ErrorType = 2006 // Too many rules in one stream
	ErrMinusKeywordsOnly            ErrorType = 2008 // You can't use minus keywords only
)

Error codes. See https://vk.com/dev/streaming_api_docs_2

func (ErrorType) Error

func (e ErrorType) Error() string

Error returns the message of a ErrorType.

type Event

type Event struct {
	EventType EventType `json:"event_type"`
	EventID   struct {
		PostOwnerID  int `json:"post_owner_id"`  // (for EventType = Post, Comment, Share)
		PostID       int `json:"post_id"`        // (for EventType = Post, Comment, Share)
		CommentID    int `json:"comment_id"`     // (for EventType = Comment)
		SharedPostID int `json:"shared_post_id"` // (for EventType = Share)
		TopicOwnerID int `json:"topic_owner_id"` // (for EventType = TopicPost)
		TopicID      int `json:"topic_id"`       // (for EventType = TopicPost)
		TopicPostID  int `json:"topic_post_id"`  // (for EventType = TopicPost)
	} `json:"event_id"`
	EventURL               string                          `json:"event_url"` // Object URL
	Text                   string                          `json:"text"`
	Action                 Action                          `json:"action"` //  action with the object
	ActionTime             int                             `json:"action_time"`
	CreationTime           int                             `json:"creation_time"` // Time when the object has been create
	Attachments            []object.WallWallpostAttachment `json:"attachments"`
	Geo                    object.BaseGeo                  `json:"geo"`
	SharedPostText         string                          `json:"shared_post_text"`
	SharedPostCreationTime int                             `json:"shared_post_creation_time"`
	SignerID               int                             `json:"signer_id"`
	Tags                   []string                        `json:"tags"`   // List of tags which correspond to the event
	Author                 Author                          `json:"author"` // Information about author
}

Event object, if status code is 100.

type EventType

type EventType string

EventType event type.

const (
	Post      EventType = "post"
	Comment   EventType = "comment"
	Share     EventType = "share"
	TopicPost EventType = "topic_post"
)

Possible values.

type Rule

type Rule struct {
	Tag   string `json:"tag"`   // rule’s tag
	Value string `json:"value"` // string representation of the rule
}

Rule struct.

Each rule has a "value", the rule’s content and a "tag". With each object you receive a list of its tags to figure out what rules does it fit.

type Streaming

type Streaming struct {
	Endpoint string // URL for further requests
	Key      string // access key for streaming api
	StreamID int

	Client    *http.Client      // A Client is an HTTP client
	Dialer    *websocket.Dialer // A Dialer contains options for connecting to WebSocket server
	UserAgent string            // UserAgent sent in the request.
	// contains filtered or unexported fields
}

Streaming struct.

func NewStreaming

func NewStreaming(vk *api.VK) (*Streaming, error)

NewStreaming returns a new Streaming.

This can be called with a service token.

The Streaming will use the http.DefaultClient. This means that if the http.DefaultClient is modified by other components of your application the modifications will be picked up by the SDK as well.

func (*Streaming) AddRule

func (s *Streaming) AddRule(tag, value string) error

AddRule adds a new rule to a stream.

- the maximum length of a rule's tag (tag) in bytes — 256.

func (*Streaming) DeleteRule

func (s *Streaming) DeleteRule(tag string) error

DeleteRule removes a rule from a stream.

func (*Streaming) GetRules

func (s *Streaming) GetRules() ([]Rule, error)

GetRules gets current rules from a stream.

func (*Streaming) OnEvent

func (s *Streaming) OnEvent(f func(Event))

OnEvent event handler.

func (*Streaming) Run

func (s *Streaming) Run() error

Run starting stream.

func (*Streaming) Shutdown

func (s *Streaming) Shutdown()

Shutdown gracefully shuts down the stream.

func (*Streaming) UpdateRules

func (s *Streaming) UpdateRules(rules []Rule) error

UpdateRules removes all rules and adds a new rule to a stream.