Share images#

The Cloud Images API enables image owners to share images that they have created with others and to use images created by someone else. See Image sharing to learn more about the fundamental concepts.

The following sections show some basic image sharing operations with cURL examples.

Note

The user with whom the image is being shared in these examples is identified by a member_id, which is the same as that user’s tenant_id.

To help you get started exploring Cloud Images, the following sections show some basic image operations with cURL examples.

Before running the examples, review the Cloud Images concepts.

Note

These examples use the $API_ENDPOINT and $AUTH_TOKEN environment variables to specify the API endpoint and authentication token values for accessing the service. Make sure you configure these variables before running the code samples.

Creating an image member#

To share an image with a particular user, you need to know who the user is, create an image member for that user, and associate the image member with the image.

Issue the following cURL command to create an image member for an image. In this example, you share the image a96be11e-8536-4910-92cb-de50aa19dfe6, which you created, with user 123456. You might have blogged about your image, and the user emailed you requesting access, so you know the user’s user ID and can use it as the value for the member parameter.

Create an image member with cURL request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members \
-X POST \
-d '{"member":"123456"}' -H "X-Auth-Token: $AUTH_TOKEN"
-H "Content-Type:application/json" |python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.

  • -s: Runs the command in silent mode.

  • -H: Specified header information. In this case, it provides the content type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

  • -d: Specifies the JSON request body.

  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Create an image member with cURL response

{
   "created_at": "2013-09-20T19:22:19Z",
   "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
   "member_id": "123456",
   "schema": "/v2/schemas/member",
   "status": "pending",
   "updated_at": "2013-09-20T19:25:31Z"
}

Listing image members#

If you want to see everyone with whom you’ve shared an image and the status of each member, list the image members.

  • Issue the following cURL command to list the image members for an image. In this example, you list members for image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL list image members request

curl -s API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members \
-H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -s: Runs the command in silent mode.

  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

List image members with cURL response

{
    "members": [
        {
            "created_at": "2013-10-07T17:58:03Z",
            "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
            "member_id": "123456",
            "schema": "/v2/schemas/member",
            "status": "pending",
            "updated_at": "2013-10-07T17:58:03Z"
        },
        {
            "created_at": "2013-10-07T17:58:55Z",
            "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
            "member_id": "9876543",
            "schema": "/v2/schemas/member",
            "status": "accepted",
            "updated_at": "2013-10-08T12:08:55Z"
        }
    ],
    "schema": "/v2/schemas/members"
}

Getting image member details#

If you want to see details for a specific image member, get the image member’s details.

  • Issue the following cURL command to get the image member’s details. In this example, you list details for member 123456 of image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL get image member details request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-H "X-Auth-Token: $AUTH_TOKEN" |python -m json.tool

Options:

  • -s: Runs the command in silent mode.

  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Get image member details response

{
    "created_at": "2013-10-07T17:58:03Z",
    "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
    "member_id": "123456",
    "schema": "/v2/schemas/member",
    "status": "pending",
    "updated_at": "2013-10-07T17:58:03Z"
}

Updating an image member#

If you send a request, outside of the Cloud Images API, to an image producer asking for access to an image, the image producer creates an image member with your tenant ID by using the instructions in Create an image member. Once the image member has been created for you, you update the image member, either accepting the image (which adds it to your image list), or rejecting the image (which notifies the producer that you received the image share notification and don’t want it in your image list).

Tip

For more information about image member statuses, see Image member statuses.

Issue the following cURL command to update an image member for an image. In this example, you (member ID 123456) accept the offer of the shared image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL update an image member request

curl -s $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-X PUT -d '{"status":"accepted"}' -H "Content-Type: application/json" -H "X-Auth-Token: $AUTH_TOKEN"|python -m json.tool

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.

  • -s: Runs the command in silent mode.

  • -H: Specified header information. In this case, it provides the content-type and the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

  • -d: Specifies the JSON request body.

  • -m json.tool: Specifies json.tool, which pretty-prints the JSON output.

Update an image member with cURL response

{
   "created_at": "2013-09-20T19:22:19Z",
   "image_id": "a96be11e-8536-4910-92cb-de50aa19dfe6",
   "member_id": "123456",
   "schema": "/v2/schemas/member",
   "status": "accepted",
   "updated_at": "2013-09-20T20:15:31Z"
}

Deleting an image member#

If you decide to no longer share your image with a user, delete that image member.

Issue the following cURL command to delete an image member for an image. In this example, you delete the user 123456 so that the user can no longer share the image a96be11e-8536-4910-92cb-de50aa19dfe6.

cURL delete an image member request

curl -i $API_ENDPOINT/v2/images/a96be11e-8536-4910-92cb-de50aa19dfe6/members/123456 \
-X DELETE \
-H "X-Auth-Token: $AUTH_TOKEN"

Options:

  • -X: Identifies the HTTP command. If no -X parameter is specified, the default is GET.

  • -i: Includes headers in the output so you can see the result of the request.

  • -H: Specified header information. In this case, it provides the authentication token. If you previously exported the token environment variable as instructed in configure these variables, you can use the $AUTH_TOKEN variable. Otherwise, substitute your actual token for the variable.

    If the operation is successful, it returns an HTTP 204 response code with no response body.