Class: Knockapi::Resources::Objects

Inherits:
Object
  • Object
show all
Defined in:
lib/knockapi/resources/objects.rb,
lib/knockapi/resources/objects/bulk.rb,
sig/knockapi/resources/objects.rbs,
sig/knockapi/resources/objects/bulk.rbs

Overview

An object represents a resource in your system that you want to map into Knock.

Defined Under Namespace

Classes: Bulk

Instance Attribute Summary collapse

Instance Method Summary collapse

Constructor Details

#initialize(client:) ⇒ Objects

This method is part of a private API. You should avoid using this method if possible, as it may be removed or be changed in the future.

Returns a new instance of Objects.

Parameters:



533
534
535
536
 
# File 'lib/knockapi/resources/objects.rb', line 533

def initialize(client:)
  @client = client
  @bulk = Knockapi::Resources::Objects::Bulk.new(client: client)
end

Instance Attribute Details

#bulk ⇒ Knockapi::Resources::Objects::Bulk (readonly)

A bulk operation is a set of changes applied across zero or more records triggered via a call to the Knock API and performed asynchronously.

Returns:



10
11
12
 
# File 'lib/knockapi/resources/objects.rb', line 10

def bulk
  @bulk
end

Instance Method Details

#add_subscriptions(collection, object_id_, recipients:, properties: nil, request_options: {}) ⇒ Array<Knockapi::Models::Recipients::Subscription>

Some parameter documentations has been truncated, see Models::ObjectAddSubscriptionsParams for more details.

Add subscriptions for an object. If a subscription already exists, it will be updated. This endpoint also handles inline identifications for the recipient.

Parameters:

Returns:

See Also:



91
92
93
94
95
96
97
98
99
100
 
# File 'lib/knockapi/resources/objects.rb', line 91

def add_subscriptions(collection, object_id_, params)
  parsed, options = Knockapi::ObjectAddSubscriptionsParams.dump_request(params)
  @client.request(
    method: :post,
    path: ["v1/objects/%1$s/%2$s/subscriptions", collection, object_id_],
    body: parsed,
    model: Knockapi::Internal::Type::ArrayOf[Knockapi::Recipients::Subscription],
    options: options
  )
end

#delete(collection, id, request_options: {}) ⇒ nil

Permanently removes an object from the specified collection. This operation cannot be undone.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • id (String) —

    Unique identifier for the object.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



59
60
61
62
63
64
65
66
 
# File 'lib/knockapi/resources/objects.rb', line 59

def delete(collection, id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/objects/%1$s/%2$s", collection, id],
    model: NilClass,
    options: params[:request_options]
  )
end

#delete_subscriptions(collection, object_id_, recipients:, request_options: {}) ⇒ Array<Knockapi::Models::Recipients::Subscription>

Some parameter documentations has been truncated, see Models::ObjectDeleteSubscriptionsParams for more details.

Delete subscriptions for the specified recipients from an object. Returns the list of deleted subscriptions.

Parameters:

Returns:

See Also:



121
122
123
124
125
126
127
128
129
130
 
# File 'lib/knockapi/resources/objects.rb', line 121

def delete_subscriptions(collection, object_id_, params)
  parsed, options = Knockapi::ObjectDeleteSubscriptionsParams.dump_request(params)
  @client.request(
    method: :delete,
    path: ["v1/objects/%1$s/%2$s/subscriptions", collection, object_id_],
    body: parsed,
    model: Knockapi::Internal::Type::ArrayOf[Knockapi::Recipients::Subscription],
    options: options
  )
end

#get(collection, id, request_options: {}) ⇒ Knockapi::Models::Object

Retrieves a specific object by its ID from the specified collection. Returns the object with all its properties.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • id (String) —

    Unique identifier for the object.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



146
147
148
149
150
151
152
153
 
# File 'lib/knockapi/resources/objects.rb', line 146

def get(collection, id, params = {})
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s", collection, id],
    model: Knockapi::Object,
    options: params[:request_options]
  )
end

#get_channel_data(collection, object_id_, channel_id, request_options: {}) ⇒ Knockapi::Models::Recipients::RecipientsChannelData

Returns the channel data for the specified object and channel.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • object_id_ (String) —

    Unique identifier for the object.

  • channel_id (String) —

    The unique identifier for the channel.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



170
171
172
173
174
175
176
177
 
# File 'lib/knockapi/resources/objects.rb', line 170

def get_channel_data(collection, object_id_, channel_id, params = {})
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/channel_data/%3$s", collection, object_id_, channel_id],
    model: Knockapi::Recipients::RecipientsChannelData,
    options: params[:request_options]
  )
end

#get_preferences(collection, object_id_, id, request_options: {}) ⇒ Knockapi::Models::Recipients::PreferenceSet

Returns the preference set for the specified object and preference set id.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • object_id_ (String) —

    Unique identifier for the object.

  • id (String) —

    Unique identifier for the preference set.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



194
195
196
197
198
199
200
201
 
# File 'lib/knockapi/resources/objects.rb', line 194

def get_preferences(collection, object_id_, id, params = {})
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/preferences/%3$s", collection, object_id_, id],
    model: Knockapi::Recipients::PreferenceSet,
    options: params[:request_options]
  )
end

#list(collection, after: nil, before: nil, include: nil, page_size: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::Object>

Returns a paginated list of objects from the specified collection. Optionally includes preference data for the objects.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • include (Array<Symbol, Knockapi::Models::ObjectListParams::Include>) —

    Includes preferences of the objects in the response.

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



32
33
34
35
36
37
38
39
40
41
42
43
 
# File 'lib/knockapi/resources/objects.rb', line 32

def list(collection, params = {})
  parsed, options = Knockapi::ObjectListParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s", collection],
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::Object,
    options: options
  )
end

#list_messages(collection, id, after: nil, before: nil, channel_id: nil, engagement_status: nil, inserted_at: nil, message_ids: nil, page_size: nil, source: nil, status: nil, tenant: nil, trigger_data: nil, workflow_categories: nil, workflow_recipient_run_id: nil, workflow_run_id: nil, request_options: {}) ⇒ Knockapi::Internal::ItemsCursor<Knockapi::Models::Message>

Some parameter documentations has been truncated, see Models::ObjectListMessagesParams for more details.

Returns a paginated list of messages for a specific object in the given collection. Allows filtering by message status and provides various sorting options.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • id (String) —

    Unique identifier for the object.

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • channel_id (String) —

    Limits the results to items with the corresponding channel ID.

  • engagement_status (Array<Symbol, Knockapi::Models::ObjectListMessagesParams::EngagementStatus>) —

    Limits the results to messages with the given engagement status.

  • inserted_at (Knockapi::Models::ObjectListMessagesParams::InsertedAt)
  • message_ids (Array<String>) —

    Limits the results to only the message IDs given (max 50). Note: when using this

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • source (String) —

    Limits the results to messages triggered by the given workflow key.

  • status (Array<Symbol, Knockapi::Models::ObjectListMessagesParams::Status>) —

    Limits the results to messages with the given delivery status.

  • tenant (String) —

    Limits the results to items with the corresponding tenant.

  • trigger_data (String) —

    Limits the results to only messages that were generated with the given data. See

  • workflow_categories (Array<String>) —

    Limits the results to messages related to any of the provided categories.

  • workflow_recipient_run_id (String) —

    Limits the results to messages for a specific recipient's workflow run.

  • workflow_run_id (String) —

    Limits the results to messages associated with the top-level workflow run ID ret

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



249
250
251
252
253
254
255
256
257
258
259
260
 
# File 'lib/knockapi/resources/objects.rb', line 249

def list_messages(collection, id, params = {})
  parsed, options = Knockapi::ObjectListMessagesParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/messages", collection, id],
    query: query,
    page: Knockapi::Internal::ItemsCursor,
    model: Knockapi::Message,
    options: options
  )
end

#list_preferences(collection, object_id_, request_options: {}) ⇒ Array<Knockapi::Models::Recipients::PreferenceSet>

Returns a paginated list of preference sets for the specified object.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • object_id_ (String) —

    Unique identifier for the object.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



275
276
277
278
279
280
281
282
 
# File 'lib/knockapi/resources/objects.rb', line 275

def list_preferences(collection, object_id_, params = {})
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/preferences", collection, object_id_],
    model: Knockapi::Internal::Type::ArrayOf[Knockapi::Recipients::PreferenceSet],
    options: params[:request_options]
  )
end

#list_schedules(collection, id, after: nil, before: nil, page_size: nil, tenant: nil, workflow: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::Schedule>

Returns a paginated list of schedules for an object.

Parameters:

  • collection (String) —

    The collection of the object to list schedules for.

  • id (String) —

    The ID of the object to list schedules for.

  • after (String) —

    The cursor to fetch entries after.

  • before (String) —

    The cursor to fetch entries before.

  • page_size (Integer) —

    The number of items per page (defaults to 50).

  • tenant (String) —

    Filter schedules by tenant id.

  • workflow (String) —

    Filter schedules by workflow id.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

See Also:



307
308
309
310
311
312
313
314
315
316
317
318
 
# File 'lib/knockapi/resources/objects.rb', line 307

def list_schedules(collection, id, params = {})
  parsed, options = Knockapi::ObjectListSchedulesParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/schedules", collection, id],
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::Schedule,
    options: options
  )
end

#list_subscriptions(collection, object_id_, after: nil, before: nil, include: nil, mode: nil, objects: nil, page_size: nil, recipients: nil, request_options: {}) ⇒ Knockapi::Internal::EntriesCursor<Knockapi::Models::Recipients::Subscription>

Some parameter documentations has been truncated, see Models::ObjectListSubscriptionsParams for more details.

List subscriptions for an object. Either list the recipients that subscribe to the provided object, or list the objects that the provided object is subscribed to. Determined by the mode query parameter.

Parameters:

Returns:

See Also:



352
353
354
355
356
357
358
359
360
361
362
363
 
# File 'lib/knockapi/resources/objects.rb', line 352

def list_subscriptions(collection, object_id_, params = {})
  parsed, options = Knockapi::ObjectListSubscriptionsParams.dump_request(params)
  query = Knockapi::Internal::Util.encode_query_params(parsed)
  @client.request(
    method: :get,
    path: ["v1/objects/%1$s/%2$s/subscriptions", collection, object_id_],
    query: query,
    page: Knockapi::Internal::EntriesCursor,
    model: Knockapi::Recipients::Subscription,
    options: options
  )
end

#set(collection, id, channel_data: nil, locale: nil, name: nil, preferences: nil, timezone: nil, request_options: {}) ⇒ Knockapi::Models::Object

Some parameter documentations has been truncated, see Models::ObjectSetParams for more details.

Creates a new object or updates an existing one in the specified collection. This operation is used to identify objects with their properties, as well as optional preferences and channel data.

Parameters:

Returns:

See Also:



393
394
395
396
397
398
399
400
401
402
 
# File 'lib/knockapi/resources/objects.rb', line 393

def set(collection, id, params = {})
  parsed, options = Knockapi::ObjectSetParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/objects/%1$s/%2$s", collection, id],
    body: parsed,
    model: Knockapi::Object,
    options: options
  )
end

#set_channel_data(collection, object_id_, channel_id, data:, request_options: {}) ⇒ Knockapi::Models::Recipients::RecipientsChannelData

Sets the channel data for the specified object and channel. If no object exists in the current environment for the given collection and object_id, Knock will create the object as part of this request.

Parameters:

Returns:

See Also:



423
424
425
426
427
428
429
430
431
432
 
# File 'lib/knockapi/resources/objects.rb', line 423

def set_channel_data(collection, object_id_, channel_id, params)
  parsed, options = Knockapi::ObjectSetChannelDataParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/objects/%1$s/%2$s/channel_data/%3$s", collection, object_id_, channel_id],
    body: parsed,
    model: Knockapi::Recipients::RecipientsChannelData,
    options: options
  )
end

#set_preferences(collection, object_id_, id, _persistence_strategy: nil, categories: nil, channel_types: nil, channels: nil, commercial_subscribed: nil, workflows: nil, request_options: {}) ⇒ Knockapi::Models::Recipients::PreferenceSet

Some parameter documentations has been truncated, see Models::ObjectSetPreferencesParams for more details.

Sets preferences within the given preference set. By default, this is a destructive operation and will replace any existing preferences with the preferences given. Use '__persistence_strategy': 'merge' to merge with existing preferences instead. If no object exists in the current environment for the given :collection and :object_id, Knock will create the object as part of this request. The preference set :id can be either default or a tenant.id. Learn more about per-tenant preferences.

Parameters:

Returns:

See Also:



471
472
473
474
475
476
477
478
479
480
 
# File 'lib/knockapi/resources/objects.rb', line 471

def set_preferences(collection, object_id_, id, params = {})
  parsed, options = Knockapi::ObjectSetPreferencesParams.dump_request(params)
  @client.request(
    method: :put,
    path: ["v1/objects/%1$s/%2$s/preferences/%3$s", collection, object_id_, id],
    body: parsed,
    model: Knockapi::Recipients::PreferenceSet,
    options: options
  )
end

#unset_channel_data(collection, object_id_, channel_id, request_options: {}) ⇒ nil

Unsets the channel data for the specified object and channel.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • object_id_ (String) —

    Unique identifier for the object.

  • channel_id (String) —

    The unique identifier for the channel.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



497
498
499
500
501
502
503
504
 
# File 'lib/knockapi/resources/objects.rb', line 497

def unset_channel_data(collection, object_id_, channel_id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/objects/%1$s/%2$s/channel_data/%3$s", collection, object_id_, channel_id],
    model: NilClass,
    options: params[:request_options]
  )
end

#unset_preferences(collection, object_id_, id, request_options: {}) ⇒ nil

Unsets the preference set for the object, removing it entirely.

Parameters:

  • collection (String) —

    The collection this object belongs to.

  • object_id_ (String) —

    Unique identifier for the object.

  • id (String) —

    Unique identifier for the preference set.

  • request_options (Knockapi::RequestOptions, Hash{Symbol=>Object}, nil)

Returns:

  • (nil)

See Also:



521
522
523
524
525
526
527
528
 
# File 'lib/knockapi/resources/objects.rb', line 521

def unset_preferences(collection, object_id_, id, params = {})
  @client.request(
    method: :delete,
    path: ["v1/objects/%1$s/%2$s/preferences/%3$s", collection, object_id_, id],
    model: NilClass,
    options: params[:request_options]
  )
end