DokumentationExperience PlatformAnvändarhandbok om åtkomstkontroll

Rollslutpunkt

Last update: Tue Jul 16 2024 00:00:00 GMT+0000 (Coordinated Universal Time)

Skapat för:

  • Utvecklare
NOTE
Om en användartoken skickas måste användaren av token ha rollen"org admin" för den begärda organisationen.

Roller definierar åtkomsten som en administratör, en specialist eller en slutanvändare har till resurser i organisationen. I en rollbaserad miljö för åtkomstkontroll är etableringen av användaråtkomst grupperad genom vanliga ansvarsområden och behov. En roll har en given uppsättning behörigheter och medlemmar i organisationen kan tilldelas till en eller flera roller, beroende på vilket synområde eller vilken skrivbehörighet de behöver.

Med slutpunkten /roles i det attributbaserade API:t för åtkomstkontroll kan du programmässigt hantera roller i din organisation.

Komma igång

API-slutpunkten som används i den här guiden är en del av det attributbaserade API:t för åtkomstkontroll. Innan du fortsätter bör du läsa kom igång-guiden för att få länkar till relaterad dokumentation, en guide till hur du läser exempelanropen för API i det här dokumentet och viktig information om vilka huvuden som krävs för att kunna anropa ett Experience Platform-API.

Hämta en lista med roller list

Du kan lista alla befintliga roller som tillhör din organisation genom att göra en GET-förfrågan till slutpunkten /roles.

API-format

GET /roles/

Begäran

Följande begäran hämtar en lista över roller som tillhör din organisation.

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

Svar

Ett godkänt svar returnerar en lista med roller i organisationen, inklusive information om deras respektive rolltyp, behörighetsgrupper och ämnesattribut.

{
  "roles": [
    {
      "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "name": "Administrator Role",
      "description": "Role for administrator type of responsibilities and access",
      "roleType": "user-defined",
      "permissionSets": [
        "manage-datasets",
        "manage-schemas"
      ],
      "sandboxes": [
        "prod"
      ],
      "subjectAttributes": {
        "labels": [
          "core/S1"
        ]
      },
      "createdBy": "{CREATED_BY}",
      "createdAt": 1648153201825,
      "modifiedBy": "{MODIFIED_BY}",
      "modifiedAt": 1648153201825,
      "etag": null
    }
  ],
  "_page": {
    "limit": 1,
    "count": 1
  },
  "_links": {
    "next": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    },
    "page": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    },
    "subjects": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
      "templated": true
    }
  }
}
Egenskap
Beskrivning
id
Det ID som motsvarar rollen. Detta ID genereras automatiskt.
name
Namnet på din roll.
description
Egenskapen description innehåller ytterligare information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.
permissionSets
Behörighetsuppsättningar representerar en grupp behörigheter som en administratör kan tillämpa på en roll. En administratör kan tilldela behörighetsgrupper till en roll i stället för att tilldela enskilda behörigheter. Detta gör att du kan skapa anpassade roller från en fördefinierad roll som innehåller en grupp behörigheter.
sandboxes
Den här egenskapen visar de sandlådor i organisationen som har etablerats för en viss roll.
subjectAttributes
De attribut som anger korrelationen mellan ett ämne och de plattformsresurser som de har tillgång till.
subjectAttributes.labels
Visar dataanvändningsetiketter som används för den efterfrågade rollen.

Söka efter en roll lookup

Du kan söka efter en enskild roll genom att göra en GET-förfrågan som innehåller motsvarande roleId i sökvägen för begäran.

API-format

GET /roles/{ROLE_ID}
Parameter
Beskrivning
ID:t för rollen som du vill söka efter.

Begäran

Följande begäran hämtar information för {ROLE_ID}.

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

Svar

Ett godkänt svar returnerar information om det efterfrågade roll-ID:t, inklusive information om dess rolltyp, behörighetsgrupper och ämnesattribut.

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role for administrator type of responsibilities and access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}
Egenskap
Beskrivning
id
Det ID som motsvarar rollen. Detta ID genereras automatiskt.
name
Namnet på din roll.
description
Egenskapen description innehåller ytterligare information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.
permissionSets
Behörighetsuppsättningar representerar en grupp behörigheter som en administratör kan tillämpa på en roll. En administratör kan tilldela behörighetsgrupper till en roll i stället för att tilldela enskilda behörigheter. Detta gör att du kan skapa anpassade roller från en fördefinierad roll som innehåller en grupp behörigheter.
sandboxes
Den här egenskapen visar de sandlådor i organisationen som har etablerats för en viss roll.
subjectAttributes
De attribut som anger korrelationen mellan ett ämne och de plattformsresurser som de har tillgång till.
subjectAttributes.labels
Visar dataanvändningsetiketter som används för den efterfrågade rollen.

Söka efter ämnen efter roll-ID

Du kan även hämta ämnen genom att göra en GET-förfrågan till slutpunkten /roles och ange en {ROLE_ID}.

API-format

GET /roles/{ROLE_ID}/subjects
Parameter
Beskrivning
ID för rollen som är associerad med de ämnen du vill söka efter.

Begäran

Följande begäran hämtar ämnen som är associerade med 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809.

curl -X GET \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809/subjects \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

Svar

Ett lyckat svar returnerar de ämnen som är associerade med det efterfrågade roll-ID:t, inklusive motsvarande ämne-ID och subjekttyp.

{
  "items": [
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID"
      },
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "PIRJ7WE5T3QT9Z4TCLVH86DE@AdobeID"
      },
      {
          "roleId": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
          "subjectType": "user",
          "subjectId": "WHPWE00MC26SHZ7AKBFG403D@AdobeID"
      },
  ]
  "_page": {
    "limit": 0,
    "count": 0
  },
  "_links": {
      "self": {
          "href": "/roles/{ROLE_ID}/subjects",
          "templated": false,
          "type": null,
          "method": null
      },
      "page": {
          "href": "/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
          "templated": true,
          "type": null,
          "method": null
      }
  }
}
Egenskap
Beskrivning
roleId
Det roll-ID som är associerat med det frågade ämnet.
subjectType
Den typ av ämne som frågan gäller.
subjectId
Det ID som motsvarar det frågade ämnet.

Skapa en roll create

Om du vill skapa en ny roll skickar du en POST till slutpunkten /roles och anger värden för rollens namn, beskrivning och rolltyp.

API-format

POST /roles/

Begäran

curl -X POST \
  https://platform.adobe.io/data/foundation/access-control/administration/roles \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "name": "Administrator Role",
    "description": "Role for administrator type of responsibilities and access",
    "roleType": "user-defined"
  }'
Egenskap
Beskrivning
name
Namnet på din roll. Se till att namnet på din roll är beskrivande, eftersom du kan använda det för att söka efter information om din roll.
description
(Valfritt) Ett beskrivande värde som du kan ta med för att ge mer information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.

Svar

Ett svar returnerar din nya roll, med dess motsvarande roll-ID, samt information om rolltyp, behörighetsgrupper och ämnesattribut.

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role for administrator type of responsibilities and access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}
Egenskap
Beskrivning
id
Det ID som motsvarar rollen. Detta ID genereras automatiskt.
name
Namnet på din roll.
description
Egenskapen description innehåller ytterligare information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.
permissionSets
Behörighetsuppsättningar representerar en grupp behörigheter som en administratör kan tillämpa på en roll. En administratör kan tilldela behörighetsgrupper till en roll i stället för att tilldela enskilda behörigheter. Detta gör att du kan skapa anpassade roller från en fördefinierad roll som innehåller en grupp behörigheter.
sandboxes
Den här egenskapen visar de sandlådor i organisationen som har etablerats för en viss roll.
subjectAttributes
De attribut som anger korrelationen mellan ett ämne och de plattformsresurser som de har tillgång till.
subjectAttributes.labels
Visar dataanvändningsetiketter som används för den efterfrågade rollen.

Uppdatera en roll patch

Du kan uppdatera egenskaperna för en roll genom att göra en PATCH-begäran till slutpunkten /roles och samtidigt ange motsvarande roll-ID och värden för de åtgärder som du vill tillämpa.

API-format

PATCH /roles/{ROLE_ID}
Parameter
Beskrivning
ID:t för rollen som du vill uppdatera.

Begäran

curl -X PATCH \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "operations": [
      {
        "op": "add",
        "path": "/description",
        "value": "Role with permission sets for admin type of access"
      }
    ]
  }'
Användning
Beskrivning
op
Åtgärdsanropet som används för att definiera åtgärden som krävs för att uppdatera rollen. Åtgärderna omfattar: add, replace och remove.
path
Sökvägen till den parameter som ska uppdateras.
value
Det nya värdet som du vill uppdatera parametern med.

Svar

Ett lyckat svar returnerar den uppdaterade rollen, inklusive nya värden för de egenskaper som du valde att uppdatera.

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator Role",
  "description": "Role with permission sets for admin type of access",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}
Egenskap
Beskrivning
id
Det ID som motsvarar rollen. Detta ID genereras automatiskt.
name
Namnet på din roll.
description
Egenskapen description innehåller ytterligare information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.
permissionSets
Behörighetsuppsättningar representerar en grupp behörigheter som en administratör kan tillämpa på en roll. En administratör kan tilldela behörighetsgrupper till en roll i stället för att tilldela enskilda behörigheter. Detta gör att du kan skapa anpassade roller från en fördefinierad roll som innehåller en grupp behörigheter.
sandboxes
Den här egenskapen visar de sandlådor i organisationen som har etablerats för en viss roll.
subjectAttributes
De attribut som anger korrelationen mellan ett ämne och de plattformsresurser som de har tillgång till.
subjectAttributes.labels
Visar dataanvändningsetiketter som används för den efterfrågade rollen.

Uppdatera en roll efter roll-ID put

Du kan uppdatera en roll genom att göra en PUT-förfrågan till slutpunkten /roles och ange det roll-ID som motsvarar den roll som du vill uppdatera.

API-format

PUT /roles/{ROLE_ID}

Begäran

Följande begäran uppdaterar namn, beskrivning och rolltyp för roll-ID: 3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809.

curl -X PUT \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809 \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}'
  -d'{
    "name": "Administrator role for ACME",
    "description": "New administrator role for ACME",
    "roleType": "user-defined"
  }'
Parameter
Beskrivning
name
Det uppdaterade namnet på en roll.
description
Den uppdaterade beskrivningen av en roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.

Svar

Ett godkänt svar returnerar din uppdaterade roll, inklusive nya värden för namn, beskrivning och rolltyp.

{
  "id": "3dfa045d-de58-4dfd-8ea9-e4e2c1b6d809",
  "name": "Administrator role for ACME",
  "description": "New administrator role for ACME",
  "roleType": "user-defined",
  "permissionSets": [
    "manage-datasets",
    "manage-schemas"
  ],
  "sandboxes": [
    "prod"
  ],
  "subjectAttributes": {
    "labels": [
      "core/S1"
    ]
  },
  "createdBy": "{CREATED_BY}",
  "createdAt": 1648153201825,
  "modifiedBy": "{MODIFIED_BY}",
  "modifiedAt": 1648153201825,
  "etag": null
}
Egenskap
Beskrivning
id
Det ID som motsvarar rollen. Detta ID genereras automatiskt.
name
Namnet på din roll.
description
Egenskapen description innehåller ytterligare information om din roll.
roleType
Den angivna typen av roll. Möjliga värden för rolltypen är: user-defined och system-defined.
permissionSets
Behörighetsuppsättningar representerar en grupp behörigheter som en administratör kan tillämpa på en roll. En administratör kan tilldela behörighetsgrupper till en roll i stället för att tilldela enskilda behörigheter. Detta gör att du kan skapa anpassade roller från en fördefinierad roll som innehåller en grupp behörigheter.
sandboxes
Den här egenskapen visar de sandlådor i organisationen som har etablerats för en viss roll.
subjectAttributes
De attribut som anger korrelationen mellan ett ämne och de plattformsresurser som de har tillgång till.
subjectAttributes.labels
Visar dataanvändningsetiketter som används för den efterfrågade rollen.

Uppdatera ämne efter roll-ID

Om du vill uppdatera de ämnen som är associerade med en roll gör du en PATCH-förfrågan till slutpunkten /roles samtidigt som du anger roll-ID för de ämnen som du vill uppdatera.

API-format

PATCH /roles/{ROLE_ID}/subjects
Parameter
Beskrivning
ID för rollen som är associerad med de ämnen som du vill uppdatera.

Begäran

Följande begäran uppdaterar de ämnen som är associerade med {ROLE_ID}.

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "op": "add",
        "path": "/user",
        "value": "{USER ID}"
    }
]'
Användning
Beskrivning
op
Åtgärdsanropet som används för att definiera åtgärden som krävs för att uppdatera rollen. Åtgärderna omfattar: add, replace och remove.
path
Sökvägen till den parameter som ska uppdateras.
value
Det nya värdet som du vill uppdatera parametern med.

Svar

Ett lyckat svar returnerar din uppdaterade roll, inklusive nya värden för personerna.

{
  "subjects": [
    [
      {
        "subjectId": "03Z07HFQCCUF3TUHAX274206@AdobeID",
        "subjectType": "user"
      }
    ]
  ],
  "_page": {
    "limit": 1,
    "count": 1
  },
  "_links": {
    "self": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects",
      "templated": true
    },
    "page": {
      "href": "https://platform.adobe.io:443/data/foundation/access-control/administration/roles/{ROLE_ID}/subjects?limit={limit}&start={start}&orderBy={orderBy}&property={property}",
      "templated": true
    }
  }
}

Ta bort en roll delete

Om du vill ta bort en roll gör du en DELETE-förfrågan till slutpunkten /roles samtidigt som du anger ID:t för rollen som du vill ta bort.

API-format

DELETE /roles/{ROLE_ID}
Parameter
Beskrivning
ID för rollen som du vill ta bort.

Begäran

Följande begäran tar bort rollen med ID:t {ROLE_ID}.

curl -X DELETE \
  https://platform.adobe.io/data/foundation/access-control/administration/roles/{ROLE_ID} \
  -H 'Authorization: Bearer {ACCESS_TOKEN}' \
  -H 'x-api-key: {API_KEY}' \
  -H 'x-gw-ims-org-id: {IMS_ORG}' \

Svar

Ett lyckat svar returnerar HTTP-status 204 (inget innehåll) och en tom brödtext.

Du kan bekräfta borttagningen genom att försöka utföra en sökning (GET) till rollen. Du får HTTP-statusen 404 (Hittades inte) eftersom rollen har tagits bort från administrationen.

Lägg till API-autentiseringsuppgifter apicredential

Om du vill lägga till en API-autentiseringsuppgift gör du en PATCH-begäran till /roles-slutpunkten och anger ämnenas roll-ID.

API-format

curl --location --request PATCH 'https://platform.adobe.io/data/foundation/access-control/administration/roles/<ROLE_ID>/subjects' \
--header 'Authorization: Bearer {ACCESS_TOKEN}' \
--header 'x-api-key: {API_KEY}' \
--header 'x-gw-ims-org-id: {IMS_ORG}' \
--header 'Content-Type: application/json' \
--data-raw '[
    {
        "op": "add",
        "path": "/api-integration",
        "value": "{TECHNICAL ACCOUNT ID}"
    }
]'
Användning
Beskrivning
op
Åtgärdsanropet som används för att definiera åtgärden som krävs för att uppdatera rollen. Åtgärderna omfattar: add, replace och remove.
path
Sökvägen till den parameter som ska läggas till.
value
Värdet som du vill lägga till parametern med.

Svar

Ett lyckat svar returnerar HTTP-status 204 (inget innehåll) och en tom brödtext.

recommendation-more-help
631fcab2-5cb1-46ef-ba66-fe098ac723e0