Class: Bitly::API::Group

Inherits:
Object
  • Object
show all
Includes:
Base
Defined in:
lib/bitly/api/group.rb,
lib/bitly/api/group/preferences.rb

Overview

A Group represents a subdivision of an Organization. Most API actions are taken on behalf of a user and group and groups become a container for Bitlinks and metrics.

Defined Under Namespace

Classes: List, Preferences

Instance Attribute Summary

Attributes included from Base

#response

Class Method Summary collapse

Instance Method Summary collapse

Methods included from Base

#assign_attributes

Constructor Details

#initialize(data:, client:, response: nil, organization: nil) ⇒ Bitly::API::Group

Creates a new ‘Bitly::API::Group` object.

Examples:

group = Bitly::API::Group.new(data: group_data, client: client)

Parameters:



87
88
89
90
91
92
 
# File 'lib/bitly/api/group.rb', line 87

def initialize(data:, client:, response: nil, organization: nil)
  assign_attributes(data)
  @client = client
  @response = response
  @organization = organization
end

Class Method Details

.attributes ⇒ Array<Symbol>

Returns The attributes the API returns for a group.

Returns:

  • (Array<Symbol>) —

    The attributes the API returns for a group



62
63
64
 
# File 'lib/bitly/api/group.rb', line 62

def self.attributes
  [:name, :guid, :is_active, :role, :bsds, :organization_guid]
end

.fetch(client:, group_guid:) ⇒ Bitly::API::Group

Retrieve a group from the API. It receives an authorized ‘Bitly::API::Client` object and a group guid and uses it to request

the `/groups/:group_guid` endpoint.

[‘GET /v4/groups/group_guid`](dev.bitly.com/api-reference/#getGroup)

Examples:

group = Bitly::API::Group.fetch(client: client, guid: guid)

Parameters:

Returns:



56
57
58
59
 
# File 'lib/bitly/api/group.rb', line 56

def self.fetch(client:, group_guid:)
  response = client.request(path: "/groups/#{group_guid}")
  Group.new(data: response.body, client: client, response: response)
end

.list(client:, organization_guid: nil) ⇒ Bitly::API::Group::List

Get a list of groups from the API. It receives an authorized ‘Bitly::API::Client` object and uses it to request the `/groups` endpoint, optionally passing an organization guid. [`GET /v4/groups`](dev.bitly.com/api-reference/#getGroups)

Examples:

groups = Bitly::API::Group.list(client: client)

Parameters:

Returns:



34
35
36
37
38
39
40
41
 
# File 'lib/bitly/api/group.rb', line 34

def self.list(client:, organization_guid: nil)
  params = { "organization_guid" => organization_guid }
  response = client.request(path: "/groups", params: params)
  groups = response.body["groups"].map do |group|
    Group.new(data: group, client: client)
  end
  List.new(items: groups, response: response)
end

.time_attributes ⇒ Array<Symbol>

converted to ‘Time` objects.

Returns:

  • (Array<Symbol>) —

    The attributes the API returns that need to be



67
68
69
 
# File 'lib/bitly/api/group.rb', line 67

def self.time_attributes
  [:created, :modified]
end

Instance Method Details

Gets the Bitlinks for the group. [‘GET /v4/groups/group_guid/bitlinks`](dev.bitly.com/api-reference/#getBitlinksByGroup)

Returns:



164
165
166
 
# File 'lib/bitly/api/group.rb', line 164

def bitlinks
  Bitly::API::Bitlink.list(client: @client, group_guid: guid)
end

#countries(unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::ClickMetric::List

Gets the country click metrics for the group. [‘GET /v4/groups/group_guid/countries`](dev.bitly.com/api-reference/#getGroupMetricsByCountries)

Parameters:

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



216
217
218
219
220
221
222
223
224
225
 
# File 'lib/bitly/api/group.rb', line 216

def countries(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClickMetric.list_countries_by_group(
    client: @client,
    group_guid: guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#organization ⇒ Bitly::API::Organization

Fetch the organization for the group. [‘GET /v4/organizations/organization_guid`)](dev.bitly.com/api-reference/#getOrganization)

Returns:



99
100
101
 
# File 'lib/bitly/api/group.rb', line 99

def organization
  @organization ||= Organization.fetch(client: @client, organization_guid: organization_guid)
end

#preferences ⇒ Bitly::API::Group::Preferences

Fetch the group’s preferences. [‘GET /v4/groups/group_guid/preferences`](dev.bitly.com/api-reference/#getGroupPreferences)

Returns:



108
109
110
 
# File 'lib/bitly/api/group.rb', line 108

def preferences
  @preferences ||= Group::Preferences.fetch(client: @client, group_guid: guid)
end

#qrcodes ⇒ Bitly::API::Qrcode::List

Gets the QR Codes for the group. [‘GET /v4/groups/group_guid/qr-codes`](dev.bitly.com/api-reference/#listQRMinimal)

Returns:



173
174
175
 
# File 'lib/bitly/api/group.rb', line 173

def qrcodes
  Bitly::API::Qrcode.list_by_group(client: @client, group_guid: guid)
end

#referring_networks(unit: nil, units: nil, unit_reference: nil, size: nil) ⇒ Bitly::API::ClickMetric::List

Gets the referring networks for the group. [‘GET /v4/groups/group_guid/referring_networks`](dev.bitly.com/api-reference/#GetGroupMetricsByReferringNetworks)

Parameters:

  • unit (String) (defaults to: nil) —

    A unit of time. Default is “day” and can be “minute”, “hour”, “day”, “week” or “month”

  • units (Integer) (defaults to: nil) —

    An integer representing the time units to query data for. pass -1 to return all units of time. Defaults to -1.

  • unit_reference (String) (defaults to: nil) —

    An ISO-8601 timestamp, indicating the most recent time for which to pull metrics. Will default to current time.

  • size (Integer) (defaults to: nil) —

    The number of links to be returned. Defaults to 50

Returns:



191
192
193
194
195
196
197
198
199
200
 
# File 'lib/bitly/api/group.rb', line 191

def referring_networks(unit: nil, units: nil, unit_reference: nil, size: nil)
  ClickMetric.list_referring_networks(
    client: @client,
    group_guid: guid,
    unit: unit,
    units: units,
    unit_reference: unit_reference,
    size: size
  )
end

#shorten_counts ⇒ Bitly::API::ShortenCounts

Get the shorten counts for the group. # [‘GET /v4/groups/group_guid/shorten_counts`](dev.bitly.com/api-reference/#getGroupShortenCounts)

Returns:



155
156
157
 
# File 'lib/bitly/api/group.rb', line 155

def shorten_counts
  ShortenCounts.by_group(client: @client, group_guid: guid)
end

#tags ⇒ Array<String>

Fetch the group’s tags [‘GET /v4/groups/group_guid/tags`](dev.bitly.com/api-reference/#getGroupTags)

Returns:

  • (Array<String>) 


117
118
119
 
# File 'lib/bitly/api/group.rb', line 117

def tags
  @tags ||= @client.request(path: "/groups/#{guid}/tags").body["tags"]
end

#update(name: nil, organization_guid: nil, bsds: nil) ⇒ Bitly::API::Group

Allows you to update the group’s name, organization or BSDs. If you update the organization guid and have already loaded the organization, it is nilled out so it can be reloaded with the correct guid [‘PATCH /v4/groups/group_guid`](dev.bitly.com/api-reference/#updateGroup)

Examples:

group.update(name: "New Name", organization_guid: "aaabbb")

Parameters:

  • name (String) (defaults to: nil) —

    A new name

  • organization_guid (String) (defaults to: nil) —

    A new organization guid

  • bsds (Array<String>) (defaults to: nil) —

    An array of branded short domains

Returns:



136
137
138
139
140
141
142
143
144
145
146
147
148
 
# File 'lib/bitly/api/group.rb', line 136

def update(name: nil, organization_guid: nil, bsds: nil)
  params = {
    "name" => name,
    "bsds" => bsds
  }
  if organization_guid
    params["organization_guid"] = organization_guid
    @organization = nil
  end
  @response = @client.request(path: "/groups/#{guid}", method: "PATCH", params: params)
  assign_attributes(@response.body)
  self
end